pandas 3.0.5: Match missing Int64 join keys with DataFrame.merge and validate their key cardinality

The pre-write solution search returned `NO_SAFE_MATCH` for pandas 3.0.5 and
missing-key merge behavior. The only existing local pandas candidate covers
Copy-on-Write and string dtype behavior in pandas 2.3.3, not joins.

A developer expecting SQL null semantics can write an inner merge and silently
receive matched missing-key rows. Repeated missing keys multiply those rows and
also make relationship validation fail because pandas treats them as duplicate
join keys.

The dependency closure is pinned explicitly for the Linux Python 3.12 verifier:
pandas 3.0.5, NumPy 2.5.2, python-dateutil 2.9.0.post0, and six 1.17.0.

{"case":{"believed":"An inner pandas DataFrame.merge treats missing join keys like SQL NULL, so missing keys never match one another.","caseId":"case:sha256:ef9ff23d81e561ee6f2be0955ec45f543e987aeeb9b7bf3e25b898516b1631a3","contract":["With two missing Int64 keys on each side, an inner DataFrame.merge returns four missing-key rows containing every left/right pair.","validate='one_to_one' raises pandas.errors.MergeError when the only duplicate keys on both sides are missing values.","After each side is reduced to one missing key, validate='one_to_one' succeeds and returns one missing-key match."],"goal":"Match missing Int64 join keys with DataFrame.merge and validate their key cardinality","kind":"HOW","packages":["pkg:pypi/pandas@3.0.5"],"schemaVersion":1,"symbols":["pandas.array","pandas.DataFrame.merge","pandas.errors.MergeError"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","libc":"musl","os":"linux","packageManager":"pip","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/pandas@3.0.5"],"schemaVersion":1,"symbols":["pandas.array","pandas.DataFrame.merge","pandas.errors.MergeError"],"verifierAdapter":"python@1"}

numpy==2.5.2
pandas==3.0.5
python-dateutil==2.9.0.post0
six==1.17.0

numpy==2.5.2
pandas==3.0.5
python-dateutil==2.9.0.post0
six==1.17.0

import pandas as pd


def assert_raises_merge_error(callback):
    try:
        callback()
    except pd.errors.MergeError:
        return
    raise AssertionError("expected pandas.errors.MergeError")


def make_frames():
    left = pd.DataFrame(
        {
            "key": pd.array([1, None, None], dtype="Int64"),
            "left_value": ["one", "left-a", "left-b"],
        }
    )
    right = pd.DataFrame(
        {
            "key": pd.array([None, None, 2], dtype="Int64"),
            "right_value": ["right-a", "right-b", "two"],
        }
    )
    return left, right


def test_missing_keys_match_as_a_cartesian_product():
    left, right = make_frames()

    merged = left.merge(
        right,
        on="key",
        how="inner",
        validate="many_to_many",
        indicator=True,
    )

    assert len(merged) == 4
    assert merged["key"].isna().all()
    assert set(zip(merged["left_value"], merged["right_value"])) == {
        ("left-a", "right-a"),
        ("left-a", "right-b"),
        ("left-b", "right-a"),
        ("left-b", "right-b"),
    }
    assert merged["_merge"].eq("both").all()


def test_missing_keys_participate_in_relationship_validation():
    left, right = make_frames()

    assert_raises_merge_error(
        lambda: left.merge(right, on="key", validate="one_to_one")
    )

    left_unique = left.drop_duplicates("key", keep="first")
    right_unique = right.drop_duplicates("key", keep="first")
    merged = left_unique.merge(
        right_unique,
        on="key",
        how="inner",
        validate="one_to_one",
    )

    assert len(merged) == 1
    assert pd.isna(merged.loc[0, "key"])
    assert merged.loc[0, "left_value"] == "left-a"
    assert merged.loc[0, "right_value"] == "right-a"


if __name__ == "__main__":
    test_missing_keys_match_as_a_cartesian_product()
    test_missing_keys_participate_in_relationship_validation()
    print("pandas merge contract passed")