docs: clarify gzip MTIME handling in comparison helper and fused-pipeline test docs

Follow-up to zarr-developers#4270: document that
_gzip_streams_equal_except_mtime skips bytes 4-8 (the RFC 1952 MTIME
field of the standard 10-byte gzip header), and update the
AsyncChunkTransform section comment and test docstring to note that
byte-identity is expected except for gzip's MTIME header field.

Assisted-by: ClaudeCode:claude-fable-5

Author: d-v-b

src/zarr/codecs/gzip.py

@@ -29,6 +29,13 @@ def parse_gzip_level(data: JSON) -> int:
 
 
 def _gzip_streams_equal_except_mtime(a: bytes, b: bytes) -> bool:
+    """Compare two gzip streams, ignoring the MTIME field of the header.
+
+    Per RFC 1952 the gzip header is [magic(2)][CM(1)][FLG(1)][MTIME(4)][XFL(1)][OS(1)],
+    so bytes 4-8 are MTIME. The fixed offsets assume the standard 10-byte header
+    with no FNAME/FEXTRA/FCOMMENT flags set, which holds here because numcodecs'
+    ``GZip.encode`` wraps ``gzip.GzipFile`` without a filename.
+    """
     if len(a) != len(b):
         return False
 

tests/test_fused_pipeline.py

@@ -849,7 +849,9 @@ def test_sharded_roundtrip_with_async_only_inner_codec() -> None:
 # ---------------------------------------------------------------------------
 # AsyncChunkTransform: the async per-chunk codec chain used on the async
 # fallback path. It is the async mirror of ChunkTransform, so it must produce
-# identical bytes/arrays. The default (Fused, sync-store) path never uses it;
+# identical bytes/arrays — except for gzip's embedded 4-byte MTIME header
+# field, which the assertions deliberately ignore when a GzipCodec is present.
+# The default (Fused, sync-store) path never uses it;
 # these tests drive it directly over multi-codec chains so the aa/bb loops and
 # the all-fill drop branch are exercised.
 # ---------------------------------------------------------------------------
@@ -867,8 +869,10 @@ def test_sharded_roundtrip_with_async_only_inner_codec() -> None:
 )
 def test_async_chunk_transform_matches_sync(codecs: tuple[Any, ...]) -> None:
     """`AsyncChunkTransform.decode_chunk`/`encode_chunk` must round-trip and
-    produce exactly what the synchronous `ChunkTransform` produces, across
-    array->array, array->bytes, and bytes->bytes codec combinations.
+    produce what the synchronous `ChunkTransform` produces, across
+    array->array, array->bytes, and bytes->bytes codec combinations. Output is
+    byte-identical except for gzip's embedded 4-byte MTIME header field, which
+    the assertion deliberately ignores when a GzipCodec is present.
 
     This is the async mirror of the codecs the default pipeline runs
     synchronously; a divergence here corrupts data only on the async fallback