tensogram-xarray 0.20.0__tar.gz → 0.22.0__tar.gz

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/.gitignore

@@ -10,6 +10,8 @@
 **/build/
 docs/book/
 python/**/dist/
+# Release wheel staging from `make python-dist-extras` / `make release-check`
+/dist/
 python/bindings/Cargo.lock
 rust/tensogram-grib/Cargo.lock
 rust/tensogram-netcdf/Cargo.lock
@@ -18,6 +20,11 @@ rust/tensogram-wasm/Cargo.lock
 .venv/
 **/__pycache__/
 *.pyc
+
+# cargo-mutants working directory + per-run logs
+mutants.out/
+mutants.out.*/
+mutants*.log
 python/bindings/python/tensogram/tensogram*.so
 # TODO do we want to have uv.locks ignored?
 **/uv.lock

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensogram-xarray
-Version: 0.20.0
+Version: 0.22.0
 Summary: xarray backend engine for tensogram .tgm files
 Project-URL: Homepage, https://sites.ecmwf.int/docs/tensogram/main
 Project-URL: Repository, https://github.com/ecmwf/tensogram
@@ -14,7 +14,7 @@ Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
 Requires-Python: >=3.11
 Requires-Dist: numpy
-Requires-Dist: tensogram<0.21,>=0.20.0
+Requires-Dist: tensogram<0.23,>=0.22.0
 Requires-Dist: xarray>=2022.06
 Provides-Extra: dask
 Requires-Dist: dask[array]; extra == 'dask'

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tensogram-xarray"
-version = "0.20.0"
+version = "0.22.0"
 description = "xarray backend engine for tensogram .tgm files"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,7 +18,7 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Atmospheric Science",
 ]
 dependencies = [
-    "tensogram>=0.20.0,<0.21",
+    "tensogram>=0.22.0,<0.23",
     "xarray>=2022.06",
     "numpy",
 ]

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/src/tensogram_xarray/array.py

@@ -200,11 +200,11 @@ class TensogramBackendArray(BackendArray):
         dtype: np.dtype,
         supports_range: bool,
         *,
-        verify_hash: bool = False,
         range_threshold: float = DEFAULT_RANGE_THRESHOLD,
         lock: threading.Lock | None = None,
         storage_options: dict[str, Any] | None = None,
         shared_file: Any | None = None,
+        verify_hash: bool = False,
     ):
         import tensogram
 
@@ -215,10 +215,10 @@ class TensogramBackendArray(BackendArray):
         self.shape = shape
         self.dtype = dtype
         self.supports_range = supports_range
-        self.verify_hash = verify_hash
         self.range_threshold = range_threshold
         self.storage_options = storage_options
         self._shared_file = shared_file
+        self.verify_hash = verify_hash
 
     # -- pickle support (no open handles stored) ----------------------------
 
@@ -267,12 +267,25 @@ class TensogramBackendArray(BackendArray):
                 total_elements = math.prod(self.shape)
 
                 if total_elements > 0 and total_requested / total_elements <= self.range_threshold:
+                    # Per the decode-time verification contract
+                    # (PLAN_DECODE_HASH_VERIFICATION §6, Q6): the
+                    # range-decode fast path does *not* verify
+                    # hashes — verifying a whole-frame hash would
+                    # require reading every byte the optimisation
+                    # is designed to avoid.  When `verify_hash` is
+                    # True, callers who care about integrity should
+                    # set ``range_threshold=0`` to force every read
+                    # through the full-decode path below.  We
+                    # *do* allow this fast path even under
+                    # ``verify_hash=True`` so the user keeps the
+                    # remote-fetch cost characteristics they
+                    # opted in to via ``range_threshold``; the
+                    # verification simply does not apply.
                     arr = f.file_decode_range(
                         self.msg_index,
                         obj_index=self.obj_index,
                         ranges=flat_ranges,
                         join=True,
-                        verify_hash=self.verify_hash,
                         native_byte_order=True,
                     )
                     return np.asarray(arr).reshape(out_shape)

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/src/tensogram_xarray/backend.py

@@ -55,9 +55,9 @@ class TensogramBackendEntrypoint(BackendEntrypoint):
         variable_key: str | None = None,
         message_index: int = 0,
         merge_objects: bool = False,
-        verify_hash: bool = False,
         range_threshold: float = 0.5,
         storage_options: dict[str, Any] | None = None,
+        verify_hash: bool = False,
     ) -> xr.Dataset:
         """Open a single tensogram message as an :class:`xr.Dataset`.
 
@@ -79,8 +79,6 @@ class TensogramBackendEntrypoint(BackendEntrypoint):
             If *True*, attempt to merge objects across messages by stacking
             along metadata dimensions that vary.  When *False* (default),
             only the single message at *message_index* is opened.
-        verify_hash
-            Whether to verify xxh3 hashes during decode.
         range_threshold
             Maximum fraction of total array elements (0.0-1.0) for which
             partial ``decode_range()`` is used instead of a full
@@ -88,6 +86,26 @@ class TensogramBackendEntrypoint(BackendEntrypoint):
         storage_options
             Key-value pairs forwarded to the object store backend when
             the path is a remote URL.  Ignored for local files.
+        verify_hash
+            When *True*, every full ``decode_object`` (or
+            ``file_decode_object``) call materialised by this Dataset's
+            lazy backing arrays is verified against its inline xxh3
+            hash; ``MissingHashError`` / ``HashMismatchError`` from
+            the underlying tensogram bindings propagate to the
+            caller's first read.
+
+            **Caveat — partial-range fast path is unverified.**  Per
+            the decode-time verification contract (see
+            ``plans/DESIGN.md`` §"Integrity Hashing" and
+            ``plans/WIRE_FORMAT.md`` §11.1), ``decode_range`` reads
+            only a slice of the encoded payload and cannot meaningfully
+            verify a whole-frame hash.  When ``verify_hash=True`` and
+            the lazy reader chooses ``file_decode_range`` (because
+            the requested slice is below ``range_threshold``), no
+            verification happens for that read.  Set
+            ``range_threshold=0`` to force every read through the
+            full-decode path if you need consistent integrity
+            coverage.
 
         Returns
         -------
@@ -107,9 +125,9 @@ class TensogramBackendEntrypoint(BackendEntrypoint):
                 file_path,
                 dim_names=dim_names,
                 variable_key=variable_key,
-                verify_hash=verify_hash,
                 range_threshold=range_threshold,
                 storage_options=storage_options,
+                verify_hash=verify_hash,
             )
             if not datasets:
                 return xr.Dataset()
@@ -120,9 +138,9 @@ class TensogramBackendEntrypoint(BackendEntrypoint):
             msg_index=message_index,
             dim_names=dim_names,
             variable_key=variable_key,
-            verify_hash=verify_hash,
             range_threshold=range_threshold,
             storage_options=storage_options,
+            verify_hash=verify_hash,
         )
 
         drop_set = set(drop_variables) if drop_variables else None

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/src/tensogram_xarray/merge.py

@@ -51,8 +51,8 @@ def open_datasets(
     *,
     dim_names: Sequence[str] | None = None,
     variable_key: str | None = None,
-    verify_hash: bool = False,
     range_threshold: float = 0.5,
+    verify_hash: bool = False,
     storage_options: dict[str, Any] | None = None,
 ) -> list[xr.Dataset]:
     """Open a ``.tgm`` file, auto-grouping into compatible Datasets.
@@ -69,8 +69,6 @@ def open_datasets(
         Explicit dimension names for the innermost tensor axes.
     variable_key
         Dotted metadata key path for variable naming.
-    verify_hash
-        Whether to verify hashes on decode.
     range_threshold
         Maximum fraction of total array elements for which partial
         ``decode_range()`` is used.  Default ``0.5``.
@@ -114,8 +112,8 @@ def open_datasets(
             shape=shape,
             dtype=np_dtype,
             supports_range=_supports_range_decode(obj.descriptor),
-            verify_hash=verify_hash,
             range_threshold=range_threshold,
+            verify_hash=verify_hash,
             lock=lock,
             storage_options=storage_options,
             shared_file=shared_file,
@@ -479,8 +477,8 @@ def _single_object_dataset(
         shape=shape,
         dtype=np_dtype,
         supports_range=_supports_range_decode(obj.descriptor),
-        verify_hash=verify_hash,
         range_threshold=range_threshold,
+        verify_hash=verify_hash,
         lock=lock,
         storage_options=storage_options,
         shared_file=shared_file,
@@ -532,8 +530,8 @@ def _flat_group_dataset(
             shape=obj.shape,
             dtype=np_dtype,
             supports_range=_supports_range_decode(obj.descriptor),
-            verify_hash=verify_hash,
             range_threshold=range_threshold,
+            verify_hash=verify_hash,
             lock=lock,
             storage_options=storage_options,
             shared_file=shared_file,
@@ -696,8 +694,8 @@ def _build_multi_variable_dataset(
                 shape=inner_shape,
                 dtype=np_dtype,
                 supports_range=_supports_range_decode(obj.descriptor),
-                verify_hash=verify_hash,
                 range_threshold=range_threshold,
+                verify_hash=verify_hash,
                 lock=lock,
                 storage_options=storage_options,
                 shared_file=shared_file,
@@ -786,8 +784,8 @@ def _build_multi_variable_dataset(
                     shape=inner_shape,
                     dtype=np_dtype,
                     supports_range=_supports_range_decode(obj.descriptor),
-                    verify_hash=verify_hash,
                     range_threshold=range_threshold,
+                    verify_hash=verify_hash,
                     lock=lock,
                     storage_options=storage_options,
                     shared_file=shared_file,
@@ -816,8 +814,8 @@ def _build_multi_variable_dataset(
                 shape=inner_shape,
                 dtype=np_dtype,
                 supports_range=_supports_range_decode(obj.descriptor),
-                verify_hash=verify_hash,
                 range_threshold=range_threshold,
+                verify_hash=verify_hash,
                 lock=lock,
                 storage_options=storage_options,
                 shared_file=shared_file,

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/src/tensogram_xarray/store.py

@@ -196,8 +196,6 @@ class TensogramDataStore:
         Optional user-specified dimension names for data variables.
     variable_key
         Optional dotted metadata path for variable naming.
-    verify_hash
-        Whether to verify object hashes on decode.
     range_threshold
         Maximum fraction of total array elements (0.0-1.0) for which
         partial ``decode_range()`` is used.  Default ``0.5``.
@@ -214,9 +212,9 @@ class TensogramDataStore:
         msg_index: int = 0,
         dim_names: Sequence[str] | None = None,
         variable_key: str | None = None,
-        verify_hash: bool = False,
         range_threshold: float = 0.5,
         storage_options: dict[str, Any] | None = None,
+        verify_hash: bool = False,
     ):
         import tensogram
 
@@ -225,9 +223,9 @@ class TensogramDataStore:
         self.msg_index = msg_index
         self.dim_names = dim_names
         self.variable_key = variable_key
-        self.verify_hash = verify_hash
         self.range_threshold = range_threshold
         self.storage_options = storage_options
+        self.verify_hash = verify_hash
         self._lock = threading.Lock()
         self._backend_arrays: list[TensogramBackendArray] = []
 
@@ -347,11 +345,11 @@ class TensogramDataStore:
                 shape=shape,
                 dtype=np_dtype,
                 supports_range=_supports_range_decode(desc),
-                verify_hash=self.verify_hash,
                 range_threshold=self.range_threshold,
                 lock=self._lock,
                 storage_options=self.storage_options,
                 shared_file=self._file,
+                verify_hash=self.verify_hash,
             )
             self._backend_arrays.append(backend_array)
             lazy_data = indexing.LazilyIndexedArray(backend_array)
@@ -387,11 +385,11 @@ class TensogramDataStore:
                 shape=shape,
                 dtype=np_dtype,
                 supports_range=_supports_range_decode(desc),
-                verify_hash=self.verify_hash,
                 range_threshold=self.range_threshold,
                 lock=self._lock,
                 storage_options=self.storage_options,
                 shared_file=self._file,
+                verify_hash=self.verify_hash,
             )
             self._backend_arrays.append(backend_array)
 

{tensogram_xarray-0.20.0 → tensogram_xarray-0.22.0}/tests/test_coverage.py

@@ -1782,3 +1782,271 @@ class TestMergePathDimResolution:
             "merge path must not misread message-level _extra_['dim_names'] as a per-object hint"
         )
         assert datasets, "expected at least one Dataset despite inconsistent hints"
+
+
+# ---------------------------------------------------------------------------
+# Coverage pass 4: remaining audit gaps (deterministic, no-network)
+# ---------------------------------------------------------------------------
+
+
+def _serve_tgm_bytes(msg: bytes):
+    """Serve raw .tgm *msg* bytes over a local loopback HTTP server.
+
+    Returns ``(url, shutdown)``.  ``shutdown`` must be called to stop the
+    server.  Supports Range requests so the tensogram object-store backend
+    can byte-range fetch descriptors/objects.
+    """
+    import http.server
+    import threading
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def log_message(self, fmt, *args):
+            pass
+
+        def do_HEAD(self):
+            self.send_response(200)
+            self.send_header("Content-Length", str(len(msg)))
+            self.send_header("Accept-Ranges", "bytes")
+            self.end_headers()
+
+        def do_GET(self):
+            range_header = self.headers.get("Range")
+            if range_header and range_header.startswith("bytes="):
+                spec = range_header[6:]
+                if spec.startswith("-"):
+                    n = int(spec[1:])
+                    s, e = max(0, len(msg) - n), len(msg)
+                else:
+                    parts = spec.split("-")
+                    s = int(parts[0])
+                    e = int(parts[1]) + 1 if parts[1] else len(msg)
+                    e = min(e, len(msg))
+                if s >= len(msg):
+                    self.send_response(416)
+                    self.end_headers()
+                    return
+                chunk = msg[s:e]
+                self.send_response(206)
+                self.send_header("Content-Range", f"bytes {s}-{e - 1}/{len(msg)}")
+                self.send_header("Content-Length", str(len(chunk)))
+                self.end_headers()
+                self.wfile.write(chunk)
+            else:
+                self.send_response(200)
+                self.send_header("Content-Length", str(len(msg)))
+                self.end_headers()
+                self.wfile.write(msg)
+
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    def shutdown():
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+
+    return f"http://127.0.0.1:{port}/test.tgm", shutdown
+
+
+class TestArrayGetFile:
+    """Cover array.py ``_get_file`` branches."""
+
+    def test_get_file_returns_shared(self):
+        """``_get_file`` short-circuits to the shared handle."""
+        from tensogram_xarray.array import TensogramBackendArray
+
+        sentinel = object()
+        ba = TensogramBackendArray(
+            "/nowhere.tgm",
+            0,
+            0,
+            (2,),
+            np.dtype("float32"),
+            supports_range=False,
+            shared_file=sentinel,
+        )
+        assert ba._get_file() is sentinel
+
+    def test_get_file_remote_opens_remote(self):
+        """``_get_file`` calls ``open_remote`` for a remote URL."""
+        from unittest.mock import patch
+
+        from tensogram_xarray.array import TensogramBackendArray
+
+        with (
+            patch("tensogram.is_remote_url", return_value=True),
+            patch("tensogram.TensogramFile") as mock_file,
+        ):
+            ba = TensogramBackendArray(
+                "s3://bucket/x.tgm",
+                0,
+                0,
+                (2,),
+                np.dtype("float32"),
+                supports_range=False,
+                storage_options={"region": "eu"},
+            )
+            ba._get_file()
+            mock_file.open_remote.assert_called_once_with("s3://bucket/x.tgm", {"region": "eu"})
+
+
+class TestArrayDecodeRangeFallbackReal:
+    """Cover array.py decode_range exception fallback."""
+
+    def test_file_decode_range_failure_falls_back(self, tmp_path: Path):
+        """When ``f.file_decode_range`` raises, full decode is used instead."""
+        from tensogram_xarray.array import TensogramBackendArray
+
+        data = np.arange(12, dtype=np.float32).reshape(3, 4)
+        path = str(tmp_path / "range_fail.tgm")
+        with tensogram.TensogramFile.create(path) as f:
+            f.append({"version": 3}, [(_desc([3, 4]), data)])
+
+        class _FailingRange:
+            """Wraps a real file but raises in the range-decode fast path."""
+
+            def __init__(self, inner):
+                self._inner = inner
+
+            def file_decode_range(self, *args, **kwargs):
+                raise RuntimeError("range decode unavailable")
+
+            def read_message(self, *args, **kwargs):
+                return self._inner.read_message(*args, **kwargs)
+
+        with tensogram.TensogramFile.open(path) as inner:
+            wrapper = _FailingRange(inner)
+            ba = TensogramBackendArray(
+                path,
+                0,
+                0,
+                (3, 4),
+                np.dtype("float32"),
+                supports_range=True,
+                range_threshold=1.0,
+                shared_file=wrapper,
+            )
+            result = ba._raw_indexing_method((slice(0, 1), slice(0, 2)))
+        np.testing.assert_array_equal(result, data[0:1, 0:2])
+
+
+class TestExpandKeyIntBranch:
+    """Cover array.py ``_expand_key_to_indices`` int branch."""
+
+    def test_integer_key_wrapped_in_list(self):
+        from tensogram_xarray.array import _expand_key_to_indices
+
+        result = _expand_key_to_indices((3, slice(1, 3)), (5, 10))
+        assert result[0] == [3]
+        assert result[1] == [1, 2]
+
+
+class TestMappingExtraHintErrorPaths:
+    """Cover mapping.py ``parse_extra_dim_names_hint`` error branches."""
+
+    def test_list_element_str_raises_returns_empty(self):
+        """A list whose elements fail ``str()`` yields ``{}``."""
+        from tensogram_xarray.mapping import parse_extra_dim_names_hint
+
+        class _Unstringable:
+            def __str__(self):
+                raise ValueError("cannot stringify")
+
+        assert parse_extra_dim_names_hint(2, [_Unstringable(), _Unstringable()]) == {}
+
+    def test_dict_non_int_key_returns_empty(self):
+        """A dict with a non-integer key yields ``{}``."""
+        from tensogram_xarray.mapping import parse_extra_dim_names_hint
+
+        assert parse_extra_dim_names_hint(2, {"not_an_int": "values"}) == {}
+
+
+class TestScannerRemote:
+    """Cover scanner.py remote scan path."""
+
+    def test_scan_file_remote(self):
+        """``scan_file`` opens remote URLs and decodes descriptors lazily."""
+        data = np.arange(6, dtype=np.float32)
+        msg = bytes(tensogram.encode({"version": 3, "source": "remote"}, [(_desc([6]), data)]))
+        url, shutdown = _serve_tgm_bytes(msg)
+        try:
+            index = scan_file(url)
+        finally:
+            shutdown()
+        assert len(index.objects) == 1
+        assert index.objects[0].shape == (6,)
+        assert index.objects[0].common_meta.get("source") == "remote"
+
+
+class TestMergeRemote:
+    """Cover merge.py remote shared-file open and close."""
+
+    def test_open_datasets_remote_and_close(self):
+        """``open_datasets`` opens a remote shared file and closes cleanly."""
+        data = np.arange(6, dtype=np.float32)
+        msg = bytes(tensogram.encode({"version": 3}, [(_desc([6]), data)]))
+        url, shutdown = _serve_tgm_bytes(msg)
+        try:
+            datasets = open_datasets(url)
+            assert len(datasets) >= 1
+            var = next(iter(datasets[0].data_vars.values()))
+            np.testing.assert_array_equal(var.values, data)
+            # Closing triggers the remote `_close_shared` callback.
+            for ds in datasets:
+                ds.close()
+        finally:
+            shutdown()
+
+
+class TestPartitionKeysUnhashable:
+    """Cover merge.py ``_partition_keys`` unhashable fallback."""
+
+    def test_unhashable_values_treated_as_constant(self):
+        """Values that remain unhashable after ``_make_hashable`` -> constant."""
+        # ``set`` passes through ``_make_hashable`` unchanged and a set of
+        # sets raises TypeError, exercising the except branch.
+        kv = {"flags": [{1, 2}, {3, 4}]}
+        const, vary = _partition_keys(kv)
+        assert "flags" in const
+        assert const["flags"] == {1, 2}
+        assert vary == {}
+
+
+class TestHypercubeMissingEntry:
+    """Cover merge.py missing-hypercube-entry guards."""
+
+    def test_missing_entry_without_variable_key(self, tmp_path: Path):
+        """A duplicate + a missing grid corner raises in ``_hypercube_dataset``."""
+        path = str(tmp_path / "missing_entry.tgm")
+        # 4 objects: (a,1),(a,2),(b,1),(b,1) -> 2x2 grid count matches (4) yet
+        # (b,2) is absent and (b,1) is duplicated.
+        combos = [("a", "1"), ("a", "2"), ("b", "1"), ("b", "1")]
+        with tensogram.TensogramFile.create(path) as f:
+            for k1, k2 in combos:
+                f.append(
+                    {"version": 3, "base": [{"k1": k1, "k2": k2}]},
+                    [(_desc([2, 3]), np.ones((2, 3), dtype=np.float32))],
+                )
+        with pytest.raises(ValueError, match="hypercube has a missing entry"):
+            open_datasets(path)
+
+    def test_missing_entry_with_variable_key(self, tmp_path: Path):
+        """Same defect inside a ``variable_key`` sub-group raises."""
+        path = str(tmp_path / "missing_entry_var.tgm")
+        rows = [
+            ("2t", "d1", "L1"),
+            ("2t", "d1", "L2"),
+            ("2t", "d2", "L1"),
+            ("2t", "d2", "L1"),  # duplicate; (d2, L2) missing
+            ("10u", "d1", "L1"),
+        ]
+        with tensogram.TensogramFile.create(path) as f:
+            for param, date, level in rows:
+                f.append(
+                    {"version": 3, "base": [{"param": param, "date": date, "level": level}]},
+                    [(_desc([2, 3]), np.ones((2, 3), dtype=np.float32))],
+                )
+        with pytest.raises(ValueError, match="hypercube has a missing entry"):
+            open_datasets(path, variable_key="param")

tensogram_xarray-0.22.0/tests/test_verify_hash.py

@@ -0,0 +1,123 @@
+# (C) Copyright 2026- ECMWF and individual contributors.
+#
+# This software is licensed under the terms of the Apache Licence Version 2.0
+# which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
+# In applying this licence, ECMWF does not waive the privileges and immunities
+# granted to it by virtue of its status as an intergovernmental organisation nor
+# does it submit to any jurisdiction.
+
+"""verify_hash threading through the xarray backend.
+
+The xarray backend re-exposes the upstream
+``DecodeOptions::verify_hash`` flag via the ``open_dataset(...,
+verify_hash=True)`` keyword.  When the lazy backing arrays
+materialise data via ``file_decode_object`` /
+``decode_object``, the kwarg propagates and integrity errors
+(``MissingHashError`` / ``HashMismatchError``) bubble up to
+the caller's first read.
+
+Per Q6 in ``PLAN_DECODE_HASH_VERIFICATION.md``: the partial-
+range fast path silently does *not* verify (range decode
+does not accept ``verify_hash``).  Set ``range_threshold=0``
+to force every read through the full-decode path if you
+need uniform coverage.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+import tensogram
+import xarray as xr
+
+
+def _build_unhashed_message(tmp_path) -> str:
+    """Encode a 1-object f32 message with hashing off + write to disk.
+
+    Returns the file path.  The unhashed encoding is what makes
+    cell C (`verify_hash=True` → MissingHashError) testable.
+    """
+    meta = {"version": 3}
+    desc = {
+        "type": "ntensor",
+        "ndim": 1,
+        "shape": [4],
+        "strides": [1],
+        "dtype": "float32",
+        "encoding": "none",
+        "filter": "none",
+        "compression": "none",
+    }
+    data = np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32)
+    msg = bytes(tensogram.encode(meta, [(desc, data)], hash=None))
+    path = tmp_path / "unhashed.tgm"
+    path.write_bytes(msg)
+    return str(path)
+
+
+def _build_hashed_message(tmp_path) -> str:
+    """Encode a 1-object f32 message with hashing on + write to disk."""
+    meta = {"version": 3}
+    desc = {
+        "type": "ntensor",
+        "ndim": 1,
+        "shape": [4],
+        "strides": [1],
+        "dtype": "float32",
+        "encoding": "none",
+        "filter": "none",
+        "compression": "none",
+    }
+    data = np.array([1.0, 2.0, 3.0, 4.0], dtype=np.float32)
+    msg = bytes(tensogram.encode(meta, [(desc, data)], hash="xxh3"))
+    path = tmp_path / "hashed.tgm"
+    path.write_bytes(msg)
+    return str(path)
+
+
+class TestOpenDatasetVerifyHash:
+    def test_verify_hash_default_is_false(self, tmp_path):
+        """Default ``verify_hash=False`` decodes both hashed and
+        unhashed fixtures cleanly."""
+        ds_hashed = xr.open_dataset(_build_hashed_message(tmp_path), engine="tensogram")
+        # Force materialisation.
+        np.asarray(ds_hashed[next(iter(ds_hashed.data_vars))].values)
+        ds_hashed.close()
+
+        ds_unhashed = xr.open_dataset(_build_unhashed_message(tmp_path), engine="tensogram")
+        np.asarray(ds_unhashed[next(iter(ds_unhashed.data_vars))].values)
+        ds_unhashed.close()
+
+    def test_verify_hash_true_succeeds_on_hashed_dataset(self, tmp_path):
+        """Cell B equivalent on the xarray surface: opening a
+        hashed file with ``verify_hash=True`` and pulling data
+        materialises cleanly."""
+        ds = xr.open_dataset(
+            _build_hashed_message(tmp_path),
+            engine="tensogram",
+            verify_hash=True,
+            # Force the full-decode path so the verification fires.
+            range_threshold=0.0,
+        )
+        arr = np.asarray(ds[next(iter(ds.data_vars))].values)
+        np.testing.assert_array_equal(arr, [1.0, 2.0, 3.0, 4.0])
+        ds.close()
+
+    def test_verify_hash_true_raises_missing_hash_on_unhashed(self, tmp_path):
+        """Cell C on xarray: open a hashless file with
+        ``verify_hash=True`` and the first read raises
+        ``MissingHashError`` from the underlying
+        :mod:`tensogram` bindings."""
+        ds = xr.open_dataset(
+            _build_unhashed_message(tmp_path),
+            engine="tensogram",
+            verify_hash=True,
+            # Force the full-decode path so the verification fires.
+            range_threshold=0.0,
+        )
+        try:
+            with pytest.raises(tensogram.MissingHashError) as excinfo:
+                _ = np.asarray(ds[next(iter(ds.data_vars))].values)
+            assert excinfo.value.object_index == 0
+        finally:
+            ds.close()