[Agentic] Move array hashing into a shared _combine_common substrate - #7276

🤖 Agentic pull request

This change was written by Claude (Opus 5), driven by @bjlittle. Commits carry a
Co-Authored-By trailer. Please review it as you would any other contribution —
and more sceptically, if that is your inclination.

What this does

Moves the array-hashing machinery out of lib/iris/_concatenate.py and into a
new private module, lib/iris/_combine_common.py.

This is row 1 of the roadmap in the merge and concatenate design spec (#7274),
and implements §5.1 of that spec. Nothing else in the programme lands until this
one is reviewed — it is deliberately the smallest possible first step, and it is
as much a test of whether the approach is worth continuing as it is a change.

The step-by-step plan this follows landed separately in #7275, and is at
docs/src/developers_guide/plans/2026-09-10-hashing-substrate.md if you want the
provenance. You should not need it to review this: the plan is a record of how
the change was arrived at, not an argument for it.

The hashing layer was added for concatenate in #5926. Merge needs exactly the
same capability, and today cannot have it without importing from
_concatenate.py — which _concatenate.py cannot offer, because it imports
iris.cube. The new module imports nothing from Iris at runtime, so either
engine can use it with no risk of a circular import. test_imports.py enforces
that by walking the module's AST, and a second test guards the guard so the
first cannot pass by failing to look.

This is a relocation, not a rewrite

No behaviour changes. The moved code is identical to the original apart from
dropping the leading underscore on seven names, plus three lines noted below.
Two checks you can run yourself:

1. The moved block is unchanged apart from the renames:

git show upstream/greenfield:lib/iris/_concatenate.py | sed -n '305,541p' \
  | sed -e 's/\b_hash_ndarray\b/hash_ndarray/g' -e 's/\b_hash_chunk\b/hash_chunk/g' \
        -e 's/\b_hash_aggregate\b/hash_aggregate/g' -e 's/\b_hash_array\b/hash_array/g' \
        -e 's/\b_ArrayHash\b/ArrayHash/g' -e 's/\b_array_id\b/array_id/g' \
        -e 's/\b_compute_hashes\b/compute_hashes/g' > /tmp/expected.py
sed -n '/^def hash_ndarray/,$p' lib/iris/_combine_common.py > /tmp/actual.py
diff -u /tmp/expected.py /tmp/actual.py

Output is two hunks, three lines — the de-shadowing described below.

2. No concatenate test was touched. test_hashing.py moves to the new
package unchanged but for its import lines; no other test under
lib/iris/tests/unit/concatenate/ is edited.

git diff upstream/greenfield --stat -- lib/iris/tests/unit/concatenate/

Where to actually look

Everything above is mechanical. The only part that needed judgement is the
array_id rename, in two places:

• Five call sites in _concatenate.py assigned to a local named
  array_id. Once the imported function has that name, the local shadows it and
  the next line raises UnboundLocalError. The locals are now points_id and
  bounds_id, which is what they always meant.
• Three bindings inside compute_hashes itself had the same collision. It is
  inert — no scope in that module calls the function — but it is the same trap,
  sitting in the module that defines the name. They are now _ and key.

Neither ruff nor mypy catches this class of shadowing, so it is worth a human
glance.

An open question for the reviewer

Dropping the underscore prefix makes this a move and a rename, and that is a
decision I would rather you took than I did.

The case for it: these names are now a small internal API consumed by two
modules, and the underscore no longer says anything the module's own _ prefix
does not already say.

The case against: it turns a diff you could verify by eye into one you have to
read, and it is the sole cause of all eight local renames above.

If you would rather review a pure git mv with the underscores kept, say so
and I will drop the rename. The module's location is what the rest of the
programme depends on; the spelling of the names is not, and I have no stake in
it.

Testing

pytest -n auto lib/iris/tests/unit gives 7072 passed against 7070 on
greenfield — the two additions are the new import-invariant tests. The one
pre-existing failure (test__chunk_control.py::test_netcdf_v3) and ten
pre-existing errors are unchanged by this branch and unrelated to it.