parity-diff 0.2.0__tar.gz → 0.2.1__tar.gz

{parity_diff-0.2.0/src/parity_diff.egg-info → parity_diff-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parity-diff
-Version: 0.2.0
+Version: 0.2.1
 Summary: Prove two tables in two different database engines hold the same data - without moving the data out of either engine.
 Author: Alessio Sorio
 License-Expression: MIT
@@ -34,6 +34,8 @@ Provides-Extra: all
 Requires-Dist: duckdb>=1.0; extra == "all"
 Requires-Dist: psycopg[binary]>=3.1; extra == "all"
 Requires-Dist: mysql-connector-python>=8.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.0; extra == "test"
 Dynamic: license-file
 
 # parity

{parity_diff-0.2.0 → parity_diff-0.2.1}/pyproject.toml

@@ -3,7 +3,7 @@
 # PyPI by an empty project. The import name, the CLI command and the repo are
 # all still `parity`: `pip install parity-diff` gives you `parity ...`.
 name = "parity-diff"
-version = "0.2.0"
+version = "0.2.1"
 description = "Prove two tables in two different database engines hold the same data - without moving the data out of either engine."
 readme = "README.md"
 license = "MIT"
@@ -38,6 +38,9 @@ duckdb = ["duckdb>=1.0"]
 postgres = ["psycopg[binary]>=3.1"]
 mysql = ["mysql-connector-python>=8.0"]
 all = ["duckdb>=1.0", "psycopg[binary]>=3.1", "mysql-connector-python>=8.0"]
+# Test-only dependencies, kept out of every runtime extra. Hypothesis drives
+# the generative suite (tests/test_properties.py); the core stays stdlib-only.
+test = ["hypothesis>=6.0"]
 
 [project.urls]
 Homepage = "https://github.com/Aleixiou/parity-diff"

{parity_diff-0.2.0 → parity_diff-0.2.1}/src/parity/__init__.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 
 from typing import Any
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = ["__version__", "diff", "get_dialect"]
 

{parity_diff-0.2.0 → parity_diff-0.2.1}/src/parity/dialects/base.py

@@ -275,9 +275,10 @@ class Dialect(ABC):
             # Two tables can legitimately share only their key - after
             # `--columns`/`--exclude`, or when the schemas have diverged
             # entirely. `concat_ws(chr(31), )` is a syntax error, so render a
-            # constant instead. Row *contents* then always match, while
-            # `count(*)` in the same checksum query still catches rows present
-            # on one side only, which is the only difference left to find.
+            # constant instead. The checksum query never passes an empty column
+            # set here: `segment_checksums` always folds the key in, so in that
+            # mode the key itself is what gets hashed. This branch stays as a
+            # defensive fallback for any other caller.
             return "''"
         return self._concat([self.normalize(c) for c in columns])
 
@@ -459,9 +460,23 @@ class Dialect(ABC):
         # the one function whose off-by-one would make the walker skip rows.
         offset = f"({self.wide_int(k)} - ({lo}))"
         bucket = self.int_div(f"{offset} * {n_segments}", f"({hi - lo})")
+        # Fold the *key* into every row's hash, not just the comparable columns.
+        # A count plus a content-only sum cannot see a same-content insert and
+        # delete in one bucket: the counts balance (one in, one out) and equal
+        # content sums to the same value, so the bucket reads clean - a false
+        # "identical", on data as ordinary as two rows sharing a status or an
+        # empty string. Including the key makes an inserted key and a deleted
+        # key hash to different values, so the bucket sum changes and the walker
+        # recurses in. This only ever *adds* sensitivity: a checksum that
+        # differs is always re-checked by downloading and comparing the real
+        # rows, so an incidental mismatch costs a query, never a wrong verdict.
+        # It also subsumes the no-comparable-columns mode, where the key becomes
+        # the only thing hashed. `columns` never contains the key, so the key is
+        # hashed exactly once.
+        content = self.row_hash([*key.columns, *columns])
         return (
             f"select {bucket} as seg, count(*), "
-            f"{self.sum_wide(self.row_hash(columns))} "
+            f"{self.sum_wide(content)} "
             f"from {self.qualify(table)} "
             f"where {k} >= {lo} and {k} <= {hi - 1} "
             f"group by 1"

{parity_diff-0.2.0 → parity_diff-0.2.1}/src/parity/engine.py

@@ -411,10 +411,26 @@ def diff(
                 stats.segments_checked += 1
 
                 if span <= 1:
-                    _compare_rows(
-                        pool, a, b, a_table, b_table, key_a, key_b,
-                        a_cols, b_cols, s_lo, s_hi, diffs, stats,
+                    # Only the *initial* range is ever this small: queued
+                    # sub-ranges always have span > 1 (a single-key bucket is
+                    # downloaded straight from the loop below, never re-queued).
+                    # So this is a one-key table, and it must still be checksum-
+                    # qualified rather than downloaded outright, or an identical
+                    # one-row table moves rows and breaks the zero-download
+                    # promise every other identical table keeps.
+                    fa = pool.submit(
+                        a.segment_checksums, a_table, key_a, a_cols, s_lo, s_hi, 1
                     )
+                    fb = pool.submit(
+                        b.segment_checksums, b_table, key_b, b_cols, s_lo, s_hi, 1
+                    )
+                    cs_a, cs_b = _gather(fa, fb)
+                    stats.queries += 2
+                    if cs_a.get(0, EMPTY) != cs_b.get(0, EMPTY):
+                        _compare_rows(
+                            pool, a, b, a_table, b_table, key_a, key_b,
+                            a_cols, b_cols, s_lo, s_hi, diffs, stats,
+                        )
                     continue
 
                 n = min(bisection_factor, span)

{parity_diff-0.2.0 → parity_diff-0.2.1/src/parity_diff.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: parity-diff
-Version: 0.2.0
+Version: 0.2.1
 Summary: Prove two tables in two different database engines hold the same data - without moving the data out of either engine.
 Author: Alessio Sorio
 License-Expression: MIT
@@ -34,6 +34,8 @@ Provides-Extra: all
 Requires-Dist: duckdb>=1.0; extra == "all"
 Requires-Dist: psycopg[binary]>=3.1; extra == "all"
 Requires-Dist: mysql-connector-python>=8.0; extra == "all"
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.0; extra == "test"
 Dynamic: license-file
 
 # parity

{parity_diff-0.2.0 → parity_diff-0.2.1}/src/parity_diff.egg-info/SOURCES.txt

@@ -23,5 +23,7 @@ tests/fakes.py
 tests/test_cli.py
 tests/test_encoding.py
 tests/test_engine.py
+tests/test_fuzz_encoding.py
 tests/test_integration.py
-tests/test_mysql.py
+tests/test_mysql.py
+tests/test_properties.py

{parity_diff-0.2.0 → parity_diff-0.2.1}/src/parity_diff.egg-info/requires.txt

@@ -12,3 +12,6 @@ mysql-connector-python>=8.0
 
 [postgres]
 psycopg[binary]>=3.1
+
+[test]
+hypothesis>=6.0

{parity_diff-0.2.0 → parity_diff-0.2.1}/tests/fakes.py

@@ -255,7 +255,13 @@ class FakeDialect(Dialect):
             bucket = ((k - lo) * n_segments) // span
             acc = out.setdefault(bucket, [0, 0])
             acc[0] += 1
-            acc[1] += row_hash(self.table.text(k, columns))
+            # Mirror Dialect._segment_sql: fold the key into the hash so a
+            # same-content insert and delete in one bucket cannot cancel. The
+            # integer key's canonical text is str(k), and row_text prepends it
+            # to the column text with the field separator.
+            col_text = self.table.text(k, columns)
+            combined = str(k) if not columns else f"{k}\x1f{col_text}"
+            acc[1] += row_hash(combined)
         return {i: (c, s) for i, (c, s) in out.items()}
 
     def fetch_range(

parity_diff-0.2.1/tests/test_fuzz_encoding.py

@@ -0,0 +1,347 @@
+"""Differential fuzzing of the cross-engine encoding contract.
+
+`test_encoding.py` pins the encoding with a fixed table of hand-chosen cases -
+the seventeen values CLAUDE.md section 4 was verified against. This file attacks
+the same contract from the other side: it *generates* hundreds of values, many
+of them deliberately hostile (the field separator byte itself, the NULL
+sentinel spelled as real data, emoji, combining marks, right-to-left text,
+bigint extremes, microsecond timestamps), inserts the **same Python value** into
+both engines, and asserts they render byte-identical canonical text and the same
+60-bit row hash.
+
+Because the value inserted into each side is identical, any disagreement is a
+pure *encoding* difference - exactly the class of bug that makes a migration
+look clean when a NULL quietly became an empty string, or a timestamp lost its
+microseconds on one engine only. A fixed case list can only catch the
+differences someone already thought to write down; this catches the ones nobody
+did.
+
+Values are inserted through the drivers' parameter binding, never as SQL
+literals, so an arbitrary string cannot escape into the statement - the fuzz
+input is data, not code. The run is seeded, so a failure reproduces exactly.
+
+Skips, never fails, when an engine is unreachable (see conftest).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import random
+from decimal import Decimal
+
+import pytest
+from conftest import open_duckdb, open_pg
+
+from parity.dialects.base import Dialect
+from parity.engine import diff
+from parity.types import Column
+
+# A schema and a DuckDB file of this module's own, so nothing here collides with
+# the fixtures in test_encoding.py (DuckDB permits a single writer per file).
+FUZZ_SCHEMA = "parity_fuzz"
+FUZZ_TABLE = "fuzz_values"
+SEED = 20240906
+N_RANDOM = 250
+
+# id bigint, then one column per fuzzable logical type. The tuple is
+# (name, postgres type, duckdb type).
+COLUMNS: list[tuple[str, str, str]] = [
+    ("id", "bigint", "bigint"),
+    ("s", "text", "varchar"),
+    ("i", "bigint", "bigint"),
+    ("d", "decimal(20,6)", "decimal(20,6)"),
+    ("b", "boolean", "boolean"),
+    ("dd", "date", "date"),
+    ("ts", "timestamp", "timestamp"),
+]
+VALUE_COLUMNS = [name for name, *_ in COLUMNS if name != "id"]
+
+# Characters excluded from generated strings for reasons unrelated to parity:
+# PostgreSQL's `text` type cannot store a NUL byte at all, and lone surrogates
+# have no UTF-8 encoding. Everything else - including the 0x1f field separator
+# and the two bytes of the `\N` sentinel - is fair game: a single column's
+# canonical text never involves the separator, so both engines must still
+# render these identically, and if they don't that is the bug.
+_FORBIDDEN = {"\x00"}
+
+
+def _rand_string(rng: random.Random) -> str:
+    """A random string drawn from a deliberately hostile alphabet."""
+    palette = (
+        "abcABC012 "
+        "héllo wörld"          # accented latin
+        "日本語한국어"            # CJK
+        "\U0001f389\U0001f600"  # emoji (astral plane)
+        "éñ"        # combining marks
+        "‏‮"          # RTL / override controls
+        "\x1f"                  # the field separator, as real data
+        "\t\r\n"                # whitespace controls
+    )
+    length = rng.randint(0, 24)
+    chars = [rng.choice(palette) for _ in range(length)]
+    s = "".join(c for c in chars if c not in _FORBIDDEN)
+    # Encoding round-trips as UTF-8 downstream; drop anything that cannot.
+    return s.encode("utf-8", "ignore").decode("utf-8")
+
+
+def _rand_decimal(rng: random.Random) -> Decimal:
+    """A decimal with at most 6 places, so no rounding happens at insert time.
+
+    A value with more than 6 places would be rounded into decimal(20,6) by the
+    INSERT, and if the two engines rounded it differently the *stored* values
+    would differ - a value difference masquerading as an encoding difference.
+    Six places keeps the inserted value exact on both sides.
+    """
+    unscaled = rng.randint(-(10**12), 10**12)
+    scale = rng.randint(0, 6)
+    return (Decimal(unscaled) / (Decimal(10) ** scale)).quantize(Decimal("0.000001"))
+
+
+def _rand_timestamp(rng: random.Random) -> dt.datetime:
+    """A timestamp somewhere in a wide range, to microsecond precision."""
+    base = dt.datetime(1000, 1, 1)
+    return base + dt.timedelta(
+        days=rng.randint(0, 3_000_000),
+        seconds=rng.randint(0, 86_399),
+        microseconds=rng.randint(0, 999_999),
+    )
+
+
+def _adversarial_rows() -> list[tuple]:
+    """Hand-picked hostile rows, prepended so they are always exercised.
+
+    Each is a `(s, i, d, b, dd, ts)` tuple; `None` means SQL NULL, which must
+    render as the sentinel rather than poison the row.
+    """
+    return [
+        ("", 0, Decimal("0.000000"), False, dt.date(1970, 1, 1), dt.datetime(2024, 1, 1)),
+        ("\x1f", 1, Decimal("1.500000"), True, dt.date(2024, 2, 29),
+         dt.datetime(2024, 2, 29, 13, 4, 5, 123456)),
+        # The sentinel spelled as genuine string data - both engines must still
+        # agree on how they render it, whatever the diff logic later makes of it.
+        ("\\N", -1, Decimal("-0.125000"), None, None, None),
+        ("O'Brien \"x\"", 9223372036854775807, Decimal("123456789.987654"),
+         True, dt.date(9999, 12, 31), dt.datetime(9999, 12, 31, 23, 59, 59, 999999)),
+        (None, -9223372036854775808, None, False, dt.date(1, 1, 1),
+         dt.datetime(1, 1, 1, 0, 0, 0)),
+        ("héllo 日本語 \U0001f389", None, Decimal("-99999999999999.999999"),
+         None, dt.date(2000, 1, 1), None),
+    ]
+
+
+def _rows() -> list[tuple]:
+    """The full fuzz corpus: the adversarial rows, then N random ones."""
+    rng = random.Random(SEED)
+    rows = list(_adversarial_rows())
+    for _ in range(N_RANDOM):
+        rows.append((
+            _rand_string(rng) if rng.random() > 0.1 else None,
+            rng.randint(-(2**63), 2**63 - 1) if rng.random() > 0.1 else None,
+            _rand_decimal(rng) if rng.random() > 0.1 else None,
+            rng.choice([True, False]) if rng.random() > 0.1 else None,
+            _rand_timestamp(rng).date() if rng.random() > 0.1 else None,
+            _rand_timestamp(rng) if rng.random() > 0.1 else None,
+        ))
+    return rows
+
+
+ROWS = _rows()
+
+
+# --------------------------------------------------------------------------
+# Fixtures: build an identical fuzz table in each engine.
+# --------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="module")
+def duck_fuzz(tmp_path_factory: pytest.TempPathFactory) -> Dialect:
+    """Load the fuzz corpus into a private DuckDB file, then read it back."""
+    import duckdb
+    from conftest import _duckdb_available
+
+    ok, why = _duckdb_available()
+    if not ok:
+        pytest.skip(why)
+
+    path = str(tmp_path_factory.mktemp("fuzz") / "fuzz.duckdb")
+    con = duckdb.connect(path)
+    try:
+        cols = ", ".join(f"{n} {t[1]}" for n, *t in COLUMNS)
+        con.execute(f"create table {FUZZ_TABLE} ({cols})")
+        placeholders = ", ".join(["?"] * len(COLUMNS))
+        con.executemany(
+            f"insert into {FUZZ_TABLE} values ({placeholders})",
+            [(i, *row) for i, row in enumerate(ROWS)],
+        )
+    finally:
+        con.close()
+
+    dialect = open_duckdb(path, side="B")
+    yield dialect
+    dialect.close()
+
+
+@pytest.fixture(scope="module")
+def pg_fuzz(pg_url: str) -> Dialect:
+    """Load the fuzz corpus into a private PostgreSQL schema, then read it back."""
+    import psycopg
+
+    con = psycopg.connect(pg_url, autocommit=True)
+    try:
+        con.execute(f"drop schema if exists {FUZZ_SCHEMA} cascade")
+        con.execute(f"create schema {FUZZ_SCHEMA}")
+        cols = ", ".join(f"{n} {t[0]}" for n, *t in COLUMNS)
+        con.execute(f"create table {FUZZ_SCHEMA}.{FUZZ_TABLE} ({cols})")
+        placeholders = ", ".join(["%s"] * len(COLUMNS))
+        with con.cursor() as cur:
+            cur.executemany(
+                f"insert into {FUZZ_SCHEMA}.{FUZZ_TABLE} values ({placeholders})",
+                [(i, *row) for i, row in enumerate(ROWS)],
+            )
+    finally:
+        con.close()
+
+    dialect = open_pg(pg_url, side="A")
+    yield dialect
+    dialect.close()
+
+
+def _qualified(dialect: Dialect) -> str:
+    """The fuzz table, qualified for whichever engine this is."""
+    schema = FUZZ_SCHEMA if dialect.name == "postgres" else "main"
+    return f"{schema}.{FUZZ_TABLE}"
+
+
+def _column(dialect: Dialect, name: str) -> Column:
+    """The introspected Column of the given name on this engine's fuzz table."""
+    for col in dialect.columns(_qualified(dialect)):
+        if col.name == name:
+            return col
+    raise AssertionError(f"no column {name!r} on side {dialect.side}")
+
+
+# --------------------------------------------------------------------------
+# The differential assertions.
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.postgres
+@pytest.mark.parametrize("column", VALUE_COLUMNS)
+def test_random_values_normalize_identically_across_engines(pg_fuzz, duck_fuzz, column):
+    """Every fuzzed value renders to byte-identical canonical text on both engines.
+
+    One column at a time, all rows at once. A single disagreeing row - a lost
+    microsecond, a NULL that rendered as SQL NULL instead of the sentinel, a
+    Unicode byte one engine folded - fails the test and names the row.
+    """
+    pg_col = _column(pg_fuzz, column)
+    duck_col = _column(duck_fuzz, column)
+    pg_rows = pg_fuzz.query(
+        f"select id, {pg_fuzz.normalize(pg_col)} "
+        f"from {pg_fuzz.qualify(_qualified(pg_fuzz))} order by id"
+    )
+    duck_rows = duck_fuzz.query(
+        f"select id, {duck_fuzz.normalize(duck_col)} "
+        f"from {duck_fuzz.qualify(_qualified(duck_fuzz))} order by id"
+    )
+    assert len(pg_rows) == len(duck_rows) == len(ROWS)
+    for (pid, pval), (did, dval) in zip(pg_rows, duck_rows, strict=True):
+        assert pid == did
+        assert pval == dval, (
+            f"column {column!r} row {pid}: postgres rendered {pval!r}, "
+            f"duckdb rendered {dval!r} for input {ROWS[pid][VALUE_COLUMNS.index(column)]!r}"
+        )
+
+
+@pytest.mark.postgres
+def test_random_rows_hash_identically_across_engines(pg_fuzz, duck_fuzz):
+    """The whole fuzzed row folds to the same 60-bit hash on both engines.
+
+    This is the row-level contract, not just per-column: the concatenation, the
+    separator, the coalesce, and the fold all have to agree at once, over every
+    generated row.
+    """
+    pg_cols = sorted(
+        (c for c in pg_fuzz.columns(_qualified(pg_fuzz)) if c.name != "id"),
+        key=lambda c: c.name,
+    )
+    duck_cols = sorted(
+        (c for c in duck_fuzz.columns(_qualified(duck_fuzz)) if c.name != "id"),
+        key=lambda c: c.name,
+    )
+    pg_rows = pg_fuzz.query(
+        f"select id, {pg_fuzz.row_hash(pg_cols)} "
+        f"from {pg_fuzz.qualify(_qualified(pg_fuzz))} order by id"
+    )
+    duck_rows = duck_fuzz.query(
+        f"select id, {duck_fuzz.row_hash(duck_cols)} "
+        f"from {duck_fuzz.qualify(_qualified(duck_fuzz))} order by id"
+    )
+    assert len(pg_rows) == len(duck_rows) == len(ROWS)
+    for (pid, phash), (did, dhash) in zip(pg_rows, duck_rows, strict=True):
+        assert pid == did
+        assert int(phash) == int(dhash), (
+            f"row {pid} hashed to {phash} on postgres, {dhash} on duckdb: "
+            f"input {ROWS[pid]!r}"
+        )
+        assert 0 <= int(phash) < 2**60, f"row {pid} hash out of 60-bit range"
+
+
+@pytest.mark.postgres
+def test_the_whole_engine_calls_two_fuzzed_tables_identical(pg_fuzz, duck_fuzz):
+    """End to end, over fuzzed data: the same rows in Postgres and DuckDB match.
+
+    Not just the encoding helpers - the real `diff()` walk, hashing pushed into
+    both engines and the key range bisected, over a table of hostile values.
+    Identical data must download zero rows and report identical; if any fuzzed
+    value hashed differently across engines, the walk would chase a phantom
+    difference and this would fail.
+    """
+    result = diff(pg_fuzz, duck_fuzz, _qualified(pg_fuzz), _qualified(duck_fuzz), "id")
+    assert result.identical, f"fuzzed tables reported different: {result.diffs[:5]}"
+    assert result.stats.rows_downloaded == 0
+
+
+@pytest.mark.postgres
+def test_a_single_planted_change_in_fuzzed_data_is_found(pg_fuzz, tmp_path):
+    """A parity tool that never plants a difference proves nothing (CLAUDE.md 8).
+
+    Build a fresh DuckDB copy of the fuzz corpus with exactly one row's string
+    column changed, diff the untouched Postgres table against it, and confirm
+    the real walk reports precisely that row and names the changed column - on
+    hostile fuzzed data, across two engines. Building a fresh copy (rather than
+    mutating a table a dialect already holds open) keeps the change visible: a
+    read-only dialect pins a snapshot at connect time and would not see a
+    mid-session write from another connection.
+    """
+    import duckdb
+
+    victim = 3  # an adversarial row, guaranteed present
+    path = str(tmp_path / "perturbed.duckdb")
+    con = duckdb.connect(path)
+    try:
+        cols = ", ".join(f"{n} {t[1]}" for n, *t in COLUMNS)
+        con.execute(f"create table {FUZZ_TABLE} ({cols})")
+        placeholders = ", ".join(["?"] * len(COLUMNS))
+        rows = []
+        for i, row in enumerate(ROWS):
+            r = list(row)
+            if i == victim:
+                r[VALUE_COLUMNS.index("s")] = "PERTURBED"
+            rows.append((i, *r))
+        con.executemany(f"insert into {FUZZ_TABLE} values ({placeholders})", rows)
+    finally:
+        con.close()
+
+    perturbed = open_duckdb(path, side="B")
+    try:
+        result = diff(
+            pg_fuzz, perturbed, _qualified(pg_fuzz), f"main.{FUZZ_TABLE}", "id"
+        )
+        assert [(d.key, d.kind) for d in result.diffs] == [(victim, "different")], (
+            f"expected exactly row {victim} to differ, got "
+            f"{[(d.key, d.kind) for d in result.diffs]}"
+        )
+        assert "s" in result.diffs[0].columns
+    finally:
+        perturbed.close()

parity_diff-0.2.1/tests/test_properties.py

@@ -0,0 +1,257 @@
+"""Property-based, oracle, and metamorphic tests for the bisection engine.
+
+Everything here is generative: Hypothesis builds thousands of tables and the
+tests assert properties that must hold for *all* of them, rather than for a few
+hand-picked cases. The centrepiece is the **oracle** - parity's segmented,
+network-frugal diff is checked against a trivial "download everything and
+compare in Python" reference over random inputs. Any logic error in the walk,
+the bucket arithmetic, or the row comparison shows up as a disagreement with
+the oracle, on an input no human thought to write down.
+
+All of it runs against the in-memory `FakeDialect`, so it needs no database and
+runs everywhere - and `FakeDialect.query` raises, so these also keep proving the
+engine never reaches past the dialect contract to build SQL itself.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+# Hypothesis is a test-only dependency (the `test` extra). If it is somehow
+# absent, skip this whole module rather than fail collection - a missing test
+# dependency must not look like a broken build.
+pytest.importorskip("hypothesis")
+
+from fakes import DictTable, FakeDialect
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from parity.engine import bucket_bounds, diff
+from parity.types import Column, LogicalType
+
+COLS = [
+    Column("a", LogicalType.STRING, "varchar"),
+    Column("b", LogicalType.STRING, "varchar"),
+]
+
+# Text values that avoid the field separator (0x1f) and the NULL sentinel, so
+# these tests isolate the *bisection* logic from the *encoding*. The separator
+# and sentinel get their own adversarial tests in test_fuzz_encoding.py.
+_safe_text = st.text(
+    alphabet=st.characters(blacklist_characters="\x1f", blacklist_categories=("Cs",)),
+    max_size=12,
+)
+_row = st.tuples(_safe_text, _safe_text)
+# Keys span negatives and a wide range, so bucketing edge cases are exercised.
+_key = st.integers(min_value=-(10**6), max_value=10**6)
+_table = st.dictionaries(_key, _row, max_size=60)
+
+
+def _oracle(rows_a: dict, rows_b: dict) -> list[tuple[int, str]]:
+    """The truth, computed the dumb way: compare every row directly.
+
+    parity must reproduce this exactly, however cleverly it gets there.
+    """
+    out = []
+    for k in set(rows_a) | set(rows_b):
+        a, b = rows_a.get(k), rows_b.get(k)
+        if a is None:
+            out.append((k, "only_in_b"))
+        elif b is None:
+            out.append((k, "only_in_a"))
+        elif a != b:
+            out.append((k, "different"))
+    return sorted(out)
+
+
+def _run(rows_a: dict, rows_b: dict, **kwargs):
+    """Diff two literal row dicts through the engine, over the in-memory fake."""
+    a = FakeDialect(DictTable(COLS, rows_a), side="A")
+    b = FakeDialect(DictTable(COLS, rows_b), side="B")
+    return diff(a, b, "a.t", "b.t", "id", **kwargs)
+
+
+def _kinds(result) -> list[tuple[int, str]]:
+    """The result as a sorted (key, kind) list, for comparison against the oracle."""
+    return sorted((d.key, d.kind) for d in result.diffs)
+
+
+# ---------------------------------------------------------------------------
+# The oracle: the segmented walk must equal a brute-force comparison, always.
+# ---------------------------------------------------------------------------
+
+
+@settings(max_examples=400)
+@given(a=_table, b=_table)
+def test_diff_matches_a_brute_force_oracle(a, b):
+    """For any two tables, parity's result equals comparing every row directly.
+
+    This is the whole engine under test at once. A skipped range, an
+    off-by-one bucket, a misclassified row - any of them makes this fail on
+    some generated input.
+    """
+    assert _kinds(_run(a, b)) == _oracle(a, b)
+
+
+@settings(max_examples=200)
+@given(
+    a=_table,
+    b=_table,
+    bisection_factor=st.integers(min_value=2, max_value=64),
+    threshold=st.integers(min_value=1, max_value=50),
+)
+def test_result_is_invariant_to_the_tuning_knobs(a, b, bisection_factor, threshold):
+    """bisection_factor and threshold change cost, never the verdict.
+
+    Fan-out and download-threshold are performance dials. If either changes
+    *which* rows are reported, the walk is wrong.
+    """
+    assert _kinds(_run(a, b, bisection_factor=bisection_factor, threshold=threshold)) == _oracle(a, b)
+
+
+# ---------------------------------------------------------------------------
+# Metamorphic properties: relations that must hold between related runs.
+# ---------------------------------------------------------------------------
+
+
+@settings(max_examples=200)
+@given(t=_table)
+def test_a_table_diffed_against_itself_is_identical(t):
+    """The most basic invariant, and a false match here is catastrophic."""
+    result = _run(t, t)
+    assert result.identical
+    assert result.diffs == []
+    assert result.stats.rows_downloaded == 0
+
+
+@settings(max_examples=300)
+@given(a=_table, b=_table)
+def test_diff_is_symmetric_under_side_swap(a, b):
+    """diff(A,B) and diff(B,A) are mirror images: only_in_a <-> only_in_b,
+    different stays different, same keys throughout."""
+    forward = dict(_kinds(_run(a, b)))
+    backward = dict(_kinds(_run(b, a)))
+    flip = {"only_in_a": "only_in_b", "only_in_b": "only_in_a", "different": "different"}
+    assert backward == {k: flip[v] for k, v in forward.items()}
+
+
+@settings(max_examples=200)
+@given(t=_table, extra=_table)
+def test_rows_downloaded_is_zero_exactly_when_identical(t, extra):
+    """The core efficiency promise, stated as an iff over random inputs."""
+    same = _run(t, t)
+    assert same.stats.rows_downloaded == 0 and same.identical
+
+    other = _run(t, extra)
+    if _oracle(t, extra):  # they genuinely differ
+        assert other.stats.rows_downloaded > 0 and not other.identical
+    else:
+        assert other.stats.rows_downloaded == 0 and other.identical
+
+
+@settings(max_examples=200)
+@given(
+    base=st.dictionaries(_key, _row, min_size=1, max_size=40),
+    changed=st.integers(min_value=0, max_value=39),
+)
+def test_exactly_n_changed_rows_are_found(base, changed):
+    """Change a chosen number of rows; the walk must find exactly that many."""
+    keys = sorted(base)
+    n = min(changed, len(keys))
+    b = dict(base)
+    for k in keys[:n]:
+        b[k] = (base[k][0] + "X", base[k][1])  # guaranteed different
+    result = _run(base, b)
+    assert [d.kind for d in result.diffs] == ["different"] * n
+    assert {d.key for d in result.diffs} == set(keys[:n])
+
+
+@settings(max_examples=150)
+@given(a=_table, b=_table)
+def test_excluding_every_differing_column_yields_identical(a, b):
+    """Metamorphic: a diff driven only by column values disappears when those
+    columns are excluded. Only key-presence differences can remain."""
+    result = _run(a, b, exclude=["a", "b"])
+    presence_only = sorted(
+        (k, kind) for k, kind in _oracle(a, b) if kind != "different"
+    )
+    assert _kinds(result) == presence_only
+
+
+# ---------------------------------------------------------------------------
+# bucket_bounds: the inverse of the SQL bucket expression, over the whole space.
+# ---------------------------------------------------------------------------
+
+
+def _sql_bucket(key: int, lo: int, hi: int, n: int) -> int:
+    """The SQL bucket expression in Python: which segment a key falls in."""
+    return ((key - lo) * n) // (hi - lo)
+
+
+@settings(max_examples=500)
+@given(
+    lo=st.integers(min_value=-(10**9), max_value=10**9),
+    span=st.integers(min_value=2, max_value=10**7),
+    n=st.integers(min_value=2, max_value=1000),
+)
+def test_bucket_bounds_tiles_the_range_with_no_gap_or_overlap(lo, span, n):
+    """Every key lands in exactly one bucket, and the buckets cover [lo, hi).
+
+    A gap is a row the walker never looks at while still reporting a clean
+    match - the worst failure this tool can have. Tested over the full space
+    of (lo, span, n), not a handful of seeds.
+    """
+    hi = lo + span
+    n = min(n, span)
+    prev_hi = lo
+    for i in range(n):
+        b_lo, b_hi = bucket_bounds(i, lo, hi, n)
+        assert b_lo == prev_hi, f"gap or overlap before bucket {i}"
+        assert b_lo <= b_hi
+        prev_hi = b_hi
+    assert prev_hi == hi, "buckets do not reach the end of the range"
+
+
+@settings(max_examples=300)
+@given(
+    lo=st.integers(min_value=-1000, max_value=1000),
+    span=st.integers(min_value=2, max_value=3000),
+    n=st.integers(min_value=2, max_value=200),
+    offset=st.integers(min_value=0),
+)
+def test_bucket_bounds_agrees_with_the_sql_expression_for_a_key(lo, span, n, offset):
+    """For a key in range, Python's bucket assignment matches the SQL formula.
+
+    The two must agree exactly, or the walker recurses into the wrong range.
+    """
+    hi = lo + span
+    n = min(n, span)
+    key = lo + (offset % span)
+    sql = _sql_bucket(key, lo, hi, n)
+    b_lo, b_hi = bucket_bounds(sql, lo, hi, n)
+    assert b_lo <= key < b_hi
+
+
+# ---------------------------------------------------------------------------
+# max_diffs: a capped run is a prefix of the truth, never a clean bill.
+# ---------------------------------------------------------------------------
+
+
+@settings(max_examples=150)
+@given(
+    base=st.dictionaries(_key, _row, min_size=1, max_size=40),
+    limit=st.integers(min_value=1, max_value=20),
+)
+def test_max_diffs_never_reports_identical_when_differences_exist(base, limit):
+    """Change every row, cap the report, and check the cap is honest.
+
+    A truncated run must carry the flag, must never read as identical, and must
+    return no more than the limit.
+    """
+    b = {k: (v[0] + "Z", v[1]) for k, v in base.items()}
+    result = _run(base, b, max_diffs=limit)
+
+    assert len(result.diffs) <= limit
+    if len(base) > limit:
+        assert result.truncated
+        assert not result.identical