deepdiff-rs 0.7.1__tar.gz → 0.8.0__tar.gz

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/Cargo.lock

@@ -629,7 +629,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "onix-arrow"
-version = "0.7.1"
+version = "0.8.0"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -646,7 +646,7 @@ dependencies = [
 
 [[package]]
 name = "onix-cli"
-version = "0.7.1"
+version = "0.8.0"
 dependencies = [
  "onix-core",
  "serde_json",
@@ -654,7 +654,7 @@ dependencies = [
 
 [[package]]
 name = "onix-core"
-version = "0.7.1"
+version = "0.8.0"
 dependencies = [
  "proptest",
  "serde",
@@ -665,7 +665,7 @@ dependencies = [
 
 [[package]]
 name = "onix-py"
-version = "0.7.1"
+version = "0.8.0"
 dependencies = [
  "arrow-array",
  "arrow-ipc",

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/Cargo.toml

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

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdiff-rs
-Version: 0.7.1
+Version: 0.8.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: MIT License
@@ -118,7 +118,7 @@ Pass `--ignore-order` to compare every list by value instead of by position, mir
 
 `diff_tables` compares two tables the way `DeepDiff` compares two objects. It takes any object implementing the [Arrow PyCapsule interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html) — a pyarrow `Table` or `RecordBatch`, a polars `DataFrame`, a DuckDB relation — and imports it with no Python round trip. The two tables are matched on a required, non-empty set of key columns (the table's primary key).
 
-It reports the **schema** diff (which columns were added, removed, or changed type) and the keyed **row** diff (which rows were added, removed, or changed, and which keys are duplicated). Rows are matched by the key columns; `rows_added`, `rows_removed`, and `duplicate_keys` return Arrow tables, and `summary()` counts each outcome. The per-cell diff (`cells_changed`) arrives in a later version and raises `NotImplementedError` until then.
+It reports 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`): one row per changed cell of a changed row, carrying the key columns, the `column`, its `old_value`/`new_value` in a canonical string rendering (a decimal at its native scale and a string verbatim, both matching DuckDB; a timestamp as its UTC instant, keeping its zone when aware; a cross-variant interval with its variant appended; a duration as ISO 8601 `PT<seconds>S`, never through the Arrow formatter (which can emit a `<invalid>` sentinel); numbers of differing width at the wider type, so an `f32` `0.1` shows as `0.10000000149011612` against an `f64` `0.1` — the exact rules are in the module doc of [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs)), and a `change`: `became_null`/`became_non_null` for a one-sided null, `type_changed` when the two types are not losslessly comparable (different value kinds, an aware-versus-naive timestamp, or a cross-variant interval), otherwise `value_changed` — a lossless type difference (integer or float widening, a time/duration unit change, a decimal scale change) is `value_changed` only when the value truly differs, never merely for the type. Its rows are ordered by the canonical string rendering of the key columns (so numeric keys sort as strings — `10` before `2` — nulls first), then left-schema column order. Rows are matched by the key columns; `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` return Arrow tables, and `summary()` counts each outcome.
 
 ```python
 import pyarrow as pa
@@ -137,16 +137,16 @@ right = pa.table({
 diff = diff_tables(left, right, key=["id"])
 print(diff.summary())
 print("added ids:", pa.table(diff.rows_added()).column("id").to_pylist())
-print("removed ids:", pa.table(diff.rows_removed()).column("id").to_pylist())
+print("cells changed:", pa.table(diff.cells_changed()).to_pylist())
 ```
 
 ```
-{'columns_added': 1, 'columns_removed': 0, 'columns_type_changed': 1, 'rows_added': 1, 'rows_removed': 1, 'rows_changed': 1, 'duplicate_keys': 0, 'null_keys': 0}
+{'columns_added': 1, 'columns_removed': 0, 'columns_type_changed': 1, 'rows_added': 1, 'rows_removed': 1, 'rows_changed': 1, 'duplicate_keys': 0, 'null_keys': 0, 'cells_changed': 1}
 added ids: [4]
-removed ids: [1]
+cells changed: [{'id': 3, 'column': 'amount', 'old_value': '30', 'new_value': '31', 'change': 'value_changed'}]
 ```
 
-A key appearing more than once on either side is reported in `duplicate_keys` (with `left_count` and `right_count`) and excluded from the added/removed/changed sets; a null key matches its counterpart and is counted in `null_keys`. Rows are compared by the non-key columns present on *both* sides, with onix's value semantics (integers and integral floats fold together, `1.00` equals `1.0000`, a timestamp compares by its instant across units, dictionary-encoded values equal their plain form, and null equals null); a nested non-key column is out of scope and is skipped rather than compared. The exact value-comparison rules are documented on the hashing functions in [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
+A key appearing more than once on either side is reported in `duplicate_keys` (with `left_count` and `right_count`) and excluded from the added/removed/changed sets; a null key matches its counterpart and is counted in `null_keys`. Rows are compared by the non-key columns present on *both* sides, with onix's value semantics (integers and integral floats fold together, all NaNs compare equal, `1.00` equals `1.0000`, a timestamp compares by its instant and a time or duration by its value across units, dictionary-encoded values equal their plain form, and null equals null); a nested non-key column is out of scope and is skipped rather than compared. The exact value-comparison rules are documented on the hashing functions in [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
 
 Type comparison uses the full logical Arrow type (timestamp unit and timezone, decimal precision and scale, and so on), but physical encodings that carry the same logical type compare equal — a dictionary-encoded string equals a plain string, polars' `Utf8View` equals pyarrow's `Utf8`, the list variants normalize together, and a map compares equal however a library spells it — so the same table read through pyarrow, polars, or DuckDB reports no spurious type changes. The full normalization rules are documented on `normalized_type` (and `map_entries`) in [`crates/onix-arrow/src/schema.rs`](crates/onix-arrow/src/schema.rs); nullability is ignored but reported in each record. Column names must be unique on each side; a repeated name raises `ValueError`. `diff.schema_arrow` is the same result as an Arrow table: it implements `__arrow_c_stream__`, so `polars.DataFrame(diff.schema_arrow)` and `pandas` consume it directly, and `diff.schema_arrow.to_pyarrow()` returns a `pyarrow.Table`.
 
@@ -168,8 +168,8 @@ Type comparison uses the full logical Arrow type (timestamp unit and timezone, d
 - `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) and time is `N·log N` (about 2 s for a 10M-row pair), 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; and temp disk, because each input is read twice 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), both spools resident at once, peaking at the decoded size of both inputs (about 315 MB — 161 + 154 MB uncompressed Arrow IPC — for the 1M-row fixture pair; on the order of 10 GB for the full 5 GB-per-side fixture pair, which on Linux may be a RAM-backed `tmpfs`), a full temp filesystem raising `ValueError` naming `TMPDIR`. None of these has a built-in cap: bound the row count and, for duplicate-heavy data, the key width of untrusted input. Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss`, single run, macOS on an Apple M-series laptop, 2026-09-05, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.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).
+- `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) and time is `N·log N` (about 2 s for a 10M-row pair), 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 re-reads both inputs, holds the changed rows of both sides, and renders every changed cell to a string held once in the output — so its cost is the number of changed cells times the cell width, not the changed-row count alone (every value is rendered in full). Measured, same method: with two narrow `int64` columns, 85 MB at 1M rows/side with 2% changed and 629 MB with every row changed; with a 1 KB `string` cell changed on every row, 1.18 GB at 100k rows/side and 2.34 GB at 200k (about 11.6 KB per changed row, linear, so on the order of 11.6 GB at 1M). 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), both spools resident at once, peaking at the decoded size of both inputs (about 315 MB — 161 + 154 MB uncompressed Arrow IPC — for the 1M-row fixture pair; on the order of 10 GB for the full 5 GB-per-side fixture pair, which on Linux 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, and the column widths (key columns for duplicate-heavy data, changed cells — rendered in full — for wide value columns). Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss`, single run, macOS on an Apple M-series laptop, 2026-09-05, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.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.
 
 ## Performance
@@ -226,7 +226,7 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 - `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions); `.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` comes back as a real `datetime`/`date` — 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=[...]) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `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 schema diff as JSON; `.rows_added()`, `.rows_removed()`, and `.duplicate_keys()` return Arrow tables, and `.cells_changed()` raises `NotImplementedError` until a later version.
+- `diff_tables(left, right, key=[...]) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `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 schema diff as JSON; `.rows_added()`, `.rows_removed()`, `.cells_changed()`, and `.duplicate_keys()` return Arrow tables.
 
 **CLI.** `onix diff <a.json> <b.json> [--max-depth N] [--ignore-order] [--timing]` reads both files as JSON and prints a compact, single-line DeepDiff-compatible report to stdout (`{}` when there is no difference).
 

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/README.md

@@ -100,7 +100,7 @@ Pass `--ignore-order` to compare every list by value instead of by position, mir
 
 `diff_tables` compares two tables the way `DeepDiff` compares two objects. It takes any object implementing the [Arrow PyCapsule interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html) — a pyarrow `Table` or `RecordBatch`, a polars `DataFrame`, a DuckDB relation — and imports it with no Python round trip. The two tables are matched on a required, non-empty set of key columns (the table's primary key).
 
-It reports the **schema** diff (which columns were added, removed, or changed type) and the keyed **row** diff (which rows were added, removed, or changed, and which keys are duplicated). Rows are matched by the key columns; `rows_added`, `rows_removed`, and `duplicate_keys` return Arrow tables, and `summary()` counts each outcome. The per-cell diff (`cells_changed`) arrives in a later version and raises `NotImplementedError` until then.
+It reports 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`): one row per changed cell of a changed row, carrying the key columns, the `column`, its `old_value`/`new_value` in a canonical string rendering (a decimal at its native scale and a string verbatim, both matching DuckDB; a timestamp as its UTC instant, keeping its zone when aware; a cross-variant interval with its variant appended; a duration as ISO 8601 `PT<seconds>S`, never through the Arrow formatter (which can emit a `<invalid>` sentinel); numbers of differing width at the wider type, so an `f32` `0.1` shows as `0.10000000149011612` against an `f64` `0.1` — the exact rules are in the module doc of [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs)), and a `change`: `became_null`/`became_non_null` for a one-sided null, `type_changed` when the two types are not losslessly comparable (different value kinds, an aware-versus-naive timestamp, or a cross-variant interval), otherwise `value_changed` — a lossless type difference (integer or float widening, a time/duration unit change, a decimal scale change) is `value_changed` only when the value truly differs, never merely for the type. Its rows are ordered by the canonical string rendering of the key columns (so numeric keys sort as strings — `10` before `2` — nulls first), then left-schema column order. Rows are matched by the key columns; `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` return Arrow tables, and `summary()` counts each outcome.
 
 ```python
 import pyarrow as pa
@@ -119,16 +119,16 @@ right = pa.table({
 diff = diff_tables(left, right, key=["id"])
 print(diff.summary())
 print("added ids:", pa.table(diff.rows_added()).column("id").to_pylist())
-print("removed ids:", pa.table(diff.rows_removed()).column("id").to_pylist())
+print("cells changed:", pa.table(diff.cells_changed()).to_pylist())
 ```
 
 ```
-{'columns_added': 1, 'columns_removed': 0, 'columns_type_changed': 1, 'rows_added': 1, 'rows_removed': 1, 'rows_changed': 1, 'duplicate_keys': 0, 'null_keys': 0}
+{'columns_added': 1, 'columns_removed': 0, 'columns_type_changed': 1, 'rows_added': 1, 'rows_removed': 1, 'rows_changed': 1, 'duplicate_keys': 0, 'null_keys': 0, 'cells_changed': 1}
 added ids: [4]
-removed ids: [1]
+cells changed: [{'id': 3, 'column': 'amount', 'old_value': '30', 'new_value': '31', 'change': 'value_changed'}]
 ```
 
-A key appearing more than once on either side is reported in `duplicate_keys` (with `left_count` and `right_count`) and excluded from the added/removed/changed sets; a null key matches its counterpart and is counted in `null_keys`. Rows are compared by the non-key columns present on *both* sides, with onix's value semantics (integers and integral floats fold together, `1.00` equals `1.0000`, a timestamp compares by its instant across units, dictionary-encoded values equal their plain form, and null equals null); a nested non-key column is out of scope and is skipped rather than compared. The exact value-comparison rules are documented on the hashing functions in [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
+A key appearing more than once on either side is reported in `duplicate_keys` (with `left_count` and `right_count`) and excluded from the added/removed/changed sets; a null key matches its counterpart and is counted in `null_keys`. Rows are compared by the non-key columns present on *both* sides, with onix's value semantics (integers and integral floats fold together, all NaNs compare equal, `1.00` equals `1.0000`, a timestamp compares by its instant and a time or duration by its value across units, dictionary-encoded values equal their plain form, and null equals null); a nested non-key column is out of scope and is skipped rather than compared. The exact value-comparison rules are documented on the hashing functions in [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
 
 Type comparison uses the full logical Arrow type (timestamp unit and timezone, decimal precision and scale, and so on), but physical encodings that carry the same logical type compare equal — a dictionary-encoded string equals a plain string, polars' `Utf8View` equals pyarrow's `Utf8`, the list variants normalize together, and a map compares equal however a library spells it — so the same table read through pyarrow, polars, or DuckDB reports no spurious type changes. The full normalization rules are documented on `normalized_type` (and `map_entries`) in [`crates/onix-arrow/src/schema.rs`](crates/onix-arrow/src/schema.rs); nullability is ignored but reported in each record. Column names must be unique on each side; a repeated name raises `ValueError`. `diff.schema_arrow` is the same result as an Arrow table: it implements `__arrow_c_stream__`, so `polars.DataFrame(diff.schema_arrow)` and `pandas` consume it directly, and `diff.schema_arrow.to_pyarrow()` returns a `pyarrow.Table`.
 
@@ -150,8 +150,8 @@ Type comparison uses the full logical Arrow type (timestamp unit and timezone, d
 - `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) and time is `N·log N` (about 2 s for a 10M-row pair), 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; and temp disk, because each input is read twice 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), both spools resident at once, peaking at the decoded size of both inputs (about 315 MB — 161 + 154 MB uncompressed Arrow IPC — for the 1M-row fixture pair; on the order of 10 GB for the full 5 GB-per-side fixture pair, which on Linux may be a RAM-backed `tmpfs`), a full temp filesystem raising `ValueError` naming `TMPDIR`. None of these has a built-in cap: bound the row count and, for duplicate-heavy data, the key width of untrusted input. Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss`, single run, macOS on an Apple M-series laptop, 2026-09-05, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.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).
+- `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) and time is `N·log N` (about 2 s for a 10M-row pair), 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 re-reads both inputs, holds the changed rows of both sides, and renders every changed cell to a string held once in the output — so its cost is the number of changed cells times the cell width, not the changed-row count alone (every value is rendered in full). Measured, same method: with two narrow `int64` columns, 85 MB at 1M rows/side with 2% changed and 629 MB with every row changed; with a 1 KB `string` cell changed on every row, 1.18 GB at 100k rows/side and 2.34 GB at 200k (about 11.6 KB per changed row, linear, so on the order of 11.6 GB at 1M). 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), both spools resident at once, peaking at the decoded size of both inputs (about 315 MB — 161 + 154 MB uncompressed Arrow IPC — for the 1M-row fixture pair; on the order of 10 GB for the full 5 GB-per-side fixture pair, which on Linux 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, and the column widths (key columns for duplicate-heavy data, changed cells — rendered in full — for wide value columns). Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss`, single run, macOS on an Apple M-series laptop, 2026-09-05, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.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.
 
 ## Performance
@@ -208,7 +208,7 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 - `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict` (with `str` keys), `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, and `datetime.date` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions); `.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` comes back as a real `datetime`/`date` — 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=[...]) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `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 schema diff as JSON; `.rows_added()`, `.rows_removed()`, and `.duplicate_keys()` return Arrow tables, and `.cells_changed()` raises `NotImplementedError` until a later version.
+- `diff_tables(left, right, key=[...]) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `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 schema diff as JSON; `.rows_added()`, `.rows_removed()`, `.cells_changed()`, and `.duplicate_keys()` return Arrow tables.
 
 **CLI.** `onix diff <a.json> <b.json> [--max-depth N] [--ignore-order] [--timing]` reads both files as JSON and prints a compact, single-line DeepDiff-compatible report to stdout (`{}` when there is no difference).
 

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/crates/onix-arrow/Cargo.toml

@@ -22,10 +22,13 @@ arrow-array = "=59.3.0"
 # `i256` for hashing `Decimal256` cells the same way as `Decimal128`.
 arrow-buffer = "=59.3.0"
 # `arrow-cast` decodes dictionary-encoded columns to their value type before
-# hashing, and casts a right-only duplicate key's columns to the left key
-# types; `arrow-select` filters and concatenates the output row batches. The
-# row diff re-reads each side through the caller's re-openable `TableInput`, so
-# no IPC spooling lives here — the Python bindings own that.
+# hashing, casts a right-only duplicate key's columns to the left key types,
+# strips a timestamp's timezone before rendering, and renders each changed
+# cell's value to its canonical string (`display::ArrayFormatter`);
+# `arrow-select` filters the materialized rows, concatenates the output row
+# batches, and `take`s the key columns into the per-cell diff. The row diff
+# re-reads each side through the caller's re-openable `TableInput`, so no IPC
+# spooling lives here — the Python bindings own that.
 arrow-cast = "=59.3.0"
 arrow-select = "=59.3.0"
 # Row identity is a keyed 128-bit SipHash-1-3 (`siphasher`), keyed from 16

deepdiff_rs-0.8.0/crates/onix-arrow/examples/row_diff_rss.rs

@@ -0,0 +1,252 @@
+//! Measures the keyed row diff's peak memory and wall time, to check the memory
+//! bounds the README states.
+//!
+//! Run under the OS's max-RSS reporter:
+//!
+//! ```sh
+//! cargo build -p onix-arrow --release --example row_diff_rss
+//! # linear shape (default): mostly-matching rows, 1% added/removed, ~2% changed
+//! /usr/bin/time -l target/release/examples/row_diff_rss 1000000
+//! /usr/bin/time -l target/release/examples/row_diff_rss 10000000
+//! # same shape with no changed rows: the cell pass materializes nothing, the
+//! # pass-one baseline the ~2%-changed run is measured against
+//! /usr/bin/time -l target/release/examples/row_diff_rss 1000000 nochange
+//! # every row changed (narrow int cells): the cell pass at full width
+//! /usr/bin/time -l target/release/examples/row_diff_rss 1000000 allchange
+//! # every row changed with a wide (1 KB) string cell: the rendering worst case
+//! /usr/bin/time -l target/release/examples/row_diff_rss 100000 wide 1024
+//! /usr/bin/time -l target/release/examples/row_diff_rss 200000 wide 1024
+//! # duplicate-heavy shape: every key duplicated, wide string key
+//! /usr/bin/time -l target/release/examples/row_diff_rss 1000000 dup 16
+//! /usr/bin/time -l target/release/examples/row_diff_rss 200000 dup 1024
+//! ```
+//!
+//! Each side is generated on the fly, batch by batch, and nothing is retained
+//! between batches, so the process's peak RSS is the diff's own state, not the
+//! table data. The **linear** shape (`id`, `value` int64 columns) exercises the
+//! per-row hash vectors: the left is ids `0..n`, the right `step..n + step` with
+//! `step = n / 100`, so 1% removed, 1% added, ~2% changed — and the cell pass
+//! materializes those ~2% changed rows on both sides. The **nochange** variant
+//! keeps the 1% added/removed but makes every shared row equal, so the cell pass
+//! materializes nothing: the difference in peak RSS between it and the default
+//! run is the cell pass's cost. The **allchange** variant drops the offset and
+//! changes every shared row (no added/removed), so the cell pass materializes
+//! and renders every row. The **wide** shape (`id` int64, `value` a
+//! `value_width`-byte Utf8 that differs between the sides) changes every row too
+//! and renders `value_width` bytes per changed cell — the rendering worst case,
+//! whose peak RSS scales with changed cells times cell width. The **dup** shape
+//! (`key` Utf8 of the given width, `value` int64) makes every key appear twice
+//! on each side, so every distinct
+//! key is a duplicate and the whole `duplicate_keys` report is materialized —
+//! the term that scales with distinct duplicated keys times the key width.
+
+use std::sync::Arc;
+
+use arrow_array::{ArrayRef, Int64Array, RecordBatch, RecordBatchReader, StringArray};
+use arrow_schema::{ArrowError, DataType, Field, Schema, SchemaRef};
+use onix_arrow::{TableDiffError, TableDiffOptions, TableInput, diff_tables};
+
+const BATCH: i64 = 65_536;
+
+/// The generated table shape.
+#[derive(Clone, Copy)]
+enum Shape {
+    /// `(id, value)` int64 columns; `id_offset` shifts the key range and
+    /// `change_every` perturbs a fraction of values.
+    Linear { id_offset: i64, change_every: i64 },
+    /// `(key, value)`; `key` is a `key_width`-byte string and each key value
+    /// appears twice, so every key is a duplicate.
+    Dup { key_width: usize },
+    /// `(id, value)` where `value` is a `value_width`-byte string filled with
+    /// `fill`; the two sides share every id but differ in `fill`, so every row
+    /// is changed and every changed cell renders `value_width` bytes — the
+    /// wide-cell worst case for the per-cell diff's rendering memory.
+    Wide { value_width: usize, fill: u8 },
+}
+
+/// A table generated on demand, retaining nothing between batches.
+struct Generated {
+    schema: SchemaRef,
+    rows: i64,
+    shape: Shape,
+}
+
+impl TableInput for Generated {
+    fn schema(&self) -> SchemaRef {
+        self.schema.clone()
+    }
+
+    fn open(&self) -> Result<Box<dyn RecordBatchReader + Send>, TableDiffError> {
+        Ok(Box::new(GenReader {
+            schema: self.schema.clone(),
+            rows: self.rows,
+            shape: self.shape,
+            next: 0,
+        }))
+    }
+}
+
+struct GenReader {
+    schema: SchemaRef,
+    rows: i64,
+    shape: Shape,
+    next: i64,
+}
+
+impl Iterator for GenReader {
+    type Item = Result<RecordBatch, ArrowError>;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.next >= self.rows {
+            return None;
+        }
+        let end = (self.next + BATCH).min(self.rows);
+        let columns: Vec<ArrayRef> = match self.shape {
+            Shape::Linear {
+                id_offset,
+                change_every,
+            } => {
+                let ids: Int64Array = (self.next..end).map(|i| Some(i + id_offset)).collect();
+                // The value is a function of the id, so a shared key holds the
+                // same value on both sides except every `change_every`-th id.
+                let values: Int64Array = (self.next..end)
+                    .map(|i| {
+                        let id = i + id_offset;
+                        Some(if id % change_every == 0 { id + 1 } else { id })
+                    })
+                    .collect();
+                vec![Arc::new(ids), Arc::new(values)]
+            }
+            Shape::Dup { key_width } => {
+                // Key value `i / 2`, so each distinct key appears twice.
+                let keys: StringArray = (self.next..end)
+                    .map(|i| Some(format!("{:0>width$}", i / 2, width = key_width)))
+                    .collect();
+                let values: Int64Array = (self.next..end).map(Some).collect();
+                vec![Arc::new(keys), Arc::new(values)]
+            }
+            Shape::Wide { value_width, fill } => {
+                let ids: Int64Array = (self.next..end).map(Some).collect();
+                let cell = String::from_utf8(vec![fill; value_width]).unwrap();
+                let values: StringArray = (self.next..end).map(|_| Some(cell.as_str())).collect();
+                vec![Arc::new(ids), Arc::new(values)]
+            }
+        };
+        self.next = end;
+
+        Some(RecordBatch::try_new(self.schema.clone(), columns))
+    }
+}
+
+impl RecordBatchReader for GenReader {
+    fn schema(&self) -> SchemaRef {
+        self.schema.clone()
+    }
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let rows: i64 = args
+        .get(1)
+        .and_then(|a| a.parse().ok())
+        .unwrap_or(1_000_000);
+    // Mode selects the shape: "dup" (duplicate-heavy), "wide" (all rows changed,
+    // wide string value column), "nochange"/"allchange"/default (linear int).
+    let mode = args.get(2).map_or("", String::as_str);
+    let width: usize = args
+        .get(3)
+        .and_then(|a| a.parse().ok())
+        .unwrap_or(if mode == "wide" { 1024 } else { 16 });
+
+    let (schema, left_shape, right_shape, key, label) = match mode {
+        "dup" => {
+            let schema = Arc::new(Schema::new(vec![
+                Field::new("key", DataType::Utf8, false),
+                Field::new("value", DataType::Int64, false),
+            ]));
+            let shape = Shape::Dup { key_width: width };
+            (
+                schema,
+                shape,
+                shape,
+                "key",
+                format!(" (dup, key_width={width})"),
+            )
+        }
+        "wide" => {
+            let schema = Arc::new(Schema::new(vec![
+                Field::new("id", DataType::Int64, false),
+                Field::new("value", DataType::Utf8, false),
+            ]));
+            (
+                schema,
+                Shape::Wide {
+                    value_width: width,
+                    fill: b'a',
+                },
+                Shape::Wide {
+                    value_width: width,
+                    fill: b'b',
+                },
+                "id",
+                format!(" (wide, value_width={width}, all changed)"),
+            )
+        }
+        _ => {
+            let schema = Arc::new(Schema::new(vec![
+                Field::new("id", DataType::Int64, false),
+                Field::new("value", DataType::Int64, false),
+            ]));
+            let step = (rows / 100).max(1);
+            // `nochange`: 1% added/removed but no changed rows (the pass-one
+            // baseline). `allchange`: no added/removed, every row changed.
+            // Default: 1% added/removed, ~2% changed.
+            let (id_offset, change_every, label) = match mode {
+                "nochange" => (step, i64::MAX, " (nochange baseline)"),
+                "allchange" => (0, 1, " (all changed)"),
+                _ => (step, 50, ""),
+            };
+            (
+                schema,
+                Shape::Linear {
+                    id_offset: 0,
+                    change_every: i64::MAX,
+                },
+                Shape::Linear {
+                    id_offset,
+                    change_every,
+                },
+                "id",
+                label.to_string(),
+            )
+        }
+    };
+
+    let left = Generated {
+        schema: schema.clone(),
+        rows,
+        shape: left_shape,
+    };
+    let right = Generated {
+        schema,
+        rows,
+        shape: right_shape,
+    };
+
+    let start = std::time::Instant::now();
+    let diff = diff_tables(&left, &right, &TableDiffOptions::new(vec![key.to_string()]))
+        .expect("diff succeeds");
+    let elapsed = start.elapsed();
+    let summary = diff.summary();
+
+    println!("rows per side: {rows}{label}");
+    println!("wall: {:.2}s", elapsed.as_secs_f64());
+    println!(
+        "rows_added={} rows_removed={} rows_changed={} duplicate_keys={} cells_changed={}",
+        summary.rows_added,
+        summary.rows_removed,
+        summary.rows_changed,
+        summary.duplicate_keys,
+        summary.cells_changed
+    );
+}

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/crates/onix-arrow/src/error.rs

@@ -31,9 +31,8 @@ impl fmt::Display for Side {
 
 /// Errors that can occur while diffing two tables.
 ///
-/// Marked `#[non_exhaustive]` because the later row-diff slices add their own
-/// variants (streaming/read failures and the like); matching on it must keep
-/// a wildcard arm.
+/// Marked `#[non_exhaustive]` so future work can add variants without a
+/// breaking change; matching on it must keep a wildcard arm.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum TableDiffError {
@@ -95,13 +94,32 @@ pub enum TableDiffError {
         /// The underlying error's message.
         message: String,
     },
-    /// A member of [`crate::TableDiff`] that a later version fills in was
-    /// asked for before that version exists. The per-cell changes
-    /// (`cells_changed`) arrive with a later version; `rows_added`,
-    /// `rows_removed`, and `duplicate_keys` are available.
-    NotImplemented {
-        /// The name of the member that is not implemented yet.
-        feature: &'static str,
+    /// A cell value could not be rendered to its canonical string for the
+    /// per-cell diff — for example a temporal value outside the range the
+    /// formatter can format. Reported as a typed error rather than written into
+    /// the output as error prose (which a real string cell could not be told
+    /// apart from).
+    Render {
+        /// The column whose cell could not be rendered.
+        column: String,
+        /// The underlying formatting error's message.
+        message: String,
+    },
+    /// The per-cell diff would need more than `u32::MAX` changed rows on one
+    /// side, which its row-index arrays cannot address. Bound the changed-row
+    /// count of untrusted input.
+    TooManyChangedRows {
+        /// The number of changed rows that overflowed.
+        rows: usize,
+    },
+    /// A `value_changed` cell rendered identically on both sides — a broken
+    /// invariant, not a caller error. The per-cell diff renders each side in a
+    /// common comparison form so a value change always shows two different
+    /// strings; this variant guards that guarantee and cannot fire for any real
+    /// input.
+    EqualRenderings {
+        /// The column whose two renderings were equal.
+        column: String,
     },
 }
 
@@ -137,10 +155,20 @@ impl fmt::Display for TableDiffError {
                  needs the key to be the same type on both sides"
             ),
             TableDiffError::Read { message } => write!(f, "failed to read table data: {message}"),
-            TableDiffError::NotImplemented { feature } => write!(
+            TableDiffError::Render { column, message } => write!(
                 f,
-                "{feature} is not implemented in this version; \
-                 the per-cell changes arrive in a later version"
+                "could not render a value of column {column:?} to its canonical string: {message}"
+            ),
+            TableDiffError::TooManyChangedRows { rows } => write!(
+                f,
+                "the per-cell diff has {rows} changed rows on one side, more than the \
+                 {} its row-index arrays can address; bound the changed-row count",
+                u32::MAX
+            ),
+            TableDiffError::EqualRenderings { column } => write!(
+                f,
+                "internal invariant: a value change in column {column:?} rendered identically \
+                 on both sides, which the common-form rendering is designed to prevent"
             ),
         }
     }
@@ -220,13 +248,34 @@ mod tests {
     }
 
     #[test]
-    fn not_implemented_message_names_the_feature() {
-        let error = TableDiffError::NotImplemented {
-            feature: "rows_added",
+    fn render_message_names_the_column() {
+        let error = TableDiffError::Render {
+            column: "ts".to_string(),
+            message: "Cast error".to_string(),
+        };
+        let message = error.to_string();
+        assert!(message.contains("\"ts\""));
+        assert!(message.contains("Cast error"));
+    }
+
+    #[test]
+    fn equal_renderings_message_reads_as_an_invariant() {
+        let error = TableDiffError::EqualRenderings {
+            column: "d".to_string(),
+        };
+        let message = error.to_string();
+        assert!(message.contains("\"d\""));
+        assert!(message.contains("invariant"));
+    }
+
+    #[test]
+    fn too_many_changed_rows_message_names_the_count() {
+        let error = TableDiffError::TooManyChangedRows {
+            rows: 5_000_000_000,
         };
         let message = error.to_string();
-        assert!(message.contains("rows_added"));
-        assert!(message.contains("not implemented"));
+        assert!(message.contains("5000000000"));
+        assert!(message.contains("changed-row count"));
     }
 
     #[test]

{deepdiff_rs-0.7.1 → deepdiff_rs-0.8.0}/crates/onix-arrow/src/lib.rs

@@ -1,10 +1,11 @@
 //! Table diffing for onix, over Apache Arrow.
 //!
 //! [`diff_tables`] compares two tables presented as [`TableInput`]s and returns
-//! a [`TableDiff`] carrying both the **schema** diff — which columns were added,
-//! removed, or changed type — and the keyed **row** diff — which rows were
-//! added, removed, or changed, and which keys are duplicated. The per-cell diff
-//! (`cells_changed`) arrives in a later version.
+//! 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.
 //!
 //! 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
@@ -14,9 +15,10 @@
 //!
 //! # Inputs
 //!
-//! The row diff reads each side twice (once to hash every row, once to
-//! materialize only the differing rows), so [`diff_tables`] takes a
-//! re-openable [`TableInput`] rather than a single-use `RecordBatchReader`.
+//! 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).
@@ -162,6 +164,15 @@ pub const MAX_NESTING_DEPTH: usize = 128;
 ///   nested key, a run-end-encoded column, or a type combination Arrow cannot
 ///   build.
 /// - [`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::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.
 pub fn diff_tables(
     left: &impl TableInput,
     right: &impl TableInput,