fix(zarr-metadata): require typing_extensions>=4.16 so UNSET pickles by reference

Models hold the UNSET sentinel as field values (dimension_names,
attributes), so any object graph containing a model must survive pickling
and deep-copying. A sentinel's contract is identity — state-based pickling
would produce impostor objects that fail every `is UNSET` check — which is
why typing_extensions <= 4.15 refused to pickle sentinels at all.

typing_extensions 4.16 implements Sentinel.__reduce__ as pickling by
reference (a lookup of the sentinel's name on its defining module), the same
mechanism enum members use, so the singleton identity survives the round
trip. Bump the floor and pin the behavior with tests: identity across
pickle/copy/deepcopy, models holding UNSET round-tripping, and a guard that
a non-importable sentinel still fails loudly rather than pickling by state.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: d-v-b

packages/zarr-metadata/pyproject.toml

@@ -32,7 +32,11 @@ classifiers = [
 ]
 keywords = ["zarr"]
 dependencies = [
-    "typing_extensions>=4.14",
+    # >=4.16: first release where `Sentinel` pickles by reference
+    # (`__reduce__` returns the sentinel's name), so `UNSET` — and any model
+    # holding it — can cross process boundaries and be deep-copied with its
+    # singleton identity intact. 4.15 and earlier refuse to pickle sentinels.
+    "typing_extensions>=4.16",
 ]
 
 [project.urls]

packages/zarr-metadata/src/zarr_metadata/model/_sentinel.py

@@ -8,6 +8,14 @@
 
 Check with identity: `if model.dimension_names is UNSET: ...`.
 
+Because the contract is identity, the sentinel must never be reconstructed
+from state: pickling and copying work by *reference* (typing_extensions >=
+4.16 implements `Sentinel.__reduce__` as a lookup of the sentinel's name on
+its defining module), so `pickle.loads(pickle.dumps(UNSET)) is UNSET` holds
+across process boundaries, and models holding `UNSET` pickle and deep-copy
+freely. Earlier typing_extensions releases refused to pickle sentinels
+outright — hence the `>=4.16` floor in this package's dependencies.
+
 Checker support (PEP 661 is Final; stdlib `sentinel` arrives in Python
 3.15): ty types this spelling exactly, including `is`/`is not` narrowing.
 Pyright supports it but a regression (1.1.405+, tracked as

packages/zarr-metadata/tests/model/test_sentinel.py

@@ -0,0 +1,54 @@
+"""Tests for the pickling and copying behavior of the `UNSET` sentinel.
+
+The sentinel's contract is identity, so it must never be reconstructed from
+state. typing_extensions >= 4.16 pickles sentinels by reference (a lookup of
+the sentinel's name on its defining module), which preserves the singleton
+across process boundaries; these tests pin that behavior, since models hold
+`UNSET` as field values and must survive pickling and deep-copying.
+"""
+
+from __future__ import annotations
+
+import copy
+import pickle
+
+import pytest
+from typing_extensions import Sentinel
+
+from zarr_metadata.model import UNSET, ArrayMetadataModelV3
+
+
+def test_unset_pickle_round_trip_preserves_identity() -> None:
+    restored = pickle.loads(pickle.dumps(UNSET))
+    assert restored is UNSET
+
+
+def test_unset_copy_preserves_identity() -> None:
+    assert copy.copy(UNSET) is UNSET
+    assert copy.deepcopy(UNSET) is UNSET
+
+
+def test_model_holding_unset_pickles() -> None:
+    model = ArrayMetadataModelV3.create_default(shape=(4,))
+    assert model.dimension_names is UNSET
+    restored = pickle.loads(pickle.dumps(model))
+    assert restored == model
+    assert restored.dimension_names is UNSET
+
+
+def test_model_holding_unset_deepcopies() -> None:
+    model = ArrayMetadataModelV3.create_default(shape=(4,))
+    duplicate = copy.deepcopy(model)
+    assert duplicate == model
+    assert duplicate.dimension_names is UNSET
+
+
+def test_non_importable_sentinel_fails_to_pickle() -> None:
+    """Sentinels pickle by reference, never by state. A sentinel that is not
+    an importable attribute of its module has no reference to pickle, so
+    dumping it must fail loudly — a successful dump here would mean the
+    implementation regressed to state-based pickling, which would produce
+    identity-breaking impostor objects on the receiving side."""
+    local_sentinel = Sentinel("local_sentinel")
+    with pytest.raises((pickle.PicklingError, TypeError)):
+        pickle.dumps(local_sentinel)