feat(zarr-metadata): export store-key aliases and type to_key_value with them

The six store-key Literal aliases were private and unused: only reachable
via underscore modules, and absent from every signature. Export them from
zarr_metadata.model beside their constants (matching the package's
name/constant pairing everywhere else), and key each to_key_value return
mapping by them so the store keys a model can emit are visible in its
signature. from_key_value keeps Mapping[str, bytes] input on purpose — it
accepts whole store mappings. A pair test guards export and value drift,
and the removal note now states the version-placement and JSON-suffix
conventions explicitly.

Assisted-by: ClaudeCode:claude-fable-5

Author: d-v-b

packages/zarr-metadata/changes/4119.feature.md

@@ -78,6 +78,13 @@ emits none), while an explicit empty `.zattrs` is `{}` and round-trips as a
 file. Previously `to_key_value` always emitted `.zattrs`, silently adding a
 file to stores that never had one.
 
+The store-key `Literal` aliases (`ZarrV2ArrayMetadataStoreKey`,
+`ZarrV2AttributesStoreKey`, ...) are exported from `zarr_metadata.model`
+alongside their constants, and each `to_key_value` return type is keyed by
+them, so the set of store keys a model can emit is visible in its signature.
+`from_key_value` deliberately keeps `Mapping[str, bytes]` input: it accepts
+any string-keyed store mapping and ignores unrelated keys.
+
 `to_json` returns a document that shares no mutable state with the model:
 every value that can hold a mutable container (attributes, configurations,
 extra fields, v2 codec configurations, fill values, consolidated entries) is

packages/zarr-metadata/changes/4119.removal.md

@@ -21,3 +21,12 @@ entity names are reserved for the `zarr_metadata.model` dataclasses:
 The old names are removed, not aliased. The `zarr_metadata.pydantic` field
 types take the bare entity names (`ZarrV3ArrayMetadata`, ...), matching the
 model classes they validate into.
+
+The conventions, stated once for future additions: CamelCase type names put
+the format version first (`ZarrV2ArrayMetadataJSON`,
+`ZarrV3ArrayMetadataStoreKey`), while SCREAMING_SNAKE constants and
+snake_case functions put it last (`ARRAY_METADATA_STORE_KEY_V2`,
+`validate_array_metadata_v3`). The `JSON` suffix marks a raw-document type
+whose bare name is taken by (or reserved for) a `zarr_metadata.model`
+dataclass; raw field-level types the models hold verbatim
+(`ZarrV2CodecMetadata`, `ZarrV3ExtensionField`) keep their bare names.

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

@@ -17,8 +17,11 @@
     ATTRIBUTES_STORE_KEY_V2,
     ZarrV2ArrayMetadata,
     ZarrV2ArrayMetadataPartial,
+    ZarrV2ArrayMetadataStoreKey,
+    ZarrV2AttributesStoreKey,
     ZarrV3ArrayMetadata,
     ZarrV3ArrayMetadataPartial,
+    ZarrV3ArrayMetadataStoreKey,
     ZarrV3MetadataField,
     ZarrV3NamedConfig,
 )
@@ -28,11 +31,14 @@
     GROUP_METADATA_STORE_KEY_V2,
     GROUP_METADATA_STORE_KEY_V3,
     ZarrV2ConsolidatedMetadata,
+    ZarrV2ConsolidatedMetadataStoreKey,
     ZarrV2GroupMetadata,
     ZarrV2GroupMetadataPartial,
+    ZarrV2GroupMetadataStoreKey,
     ZarrV3ConsolidatedMetadata,
     ZarrV3GroupMetadata,
     ZarrV3GroupMetadataPartial,
+    ZarrV3GroupMetadataStoreKey,
 )
 from zarr_metadata.model._sentinel import UNSET
 from zarr_metadata.model._validation import (
@@ -89,14 +95,20 @@
     "ValidationProblem",
     "ZarrV2ArrayMetadata",
     "ZarrV2ArrayMetadataPartial",
+    "ZarrV2ArrayMetadataStoreKey",
+    "ZarrV2AttributesStoreKey",
     "ZarrV2ConsolidatedMetadata",
+    "ZarrV2ConsolidatedMetadataStoreKey",
     "ZarrV2GroupMetadata",
     "ZarrV2GroupMetadataPartial",
+    "ZarrV2GroupMetadataStoreKey",
     "ZarrV3ArrayMetadata",
     "ZarrV3ArrayMetadataPartial",
+    "ZarrV3ArrayMetadataStoreKey",
     "ZarrV3ConsolidatedMetadata",
     "ZarrV3GroupMetadata",
     "ZarrV3GroupMetadataPartial",
+    "ZarrV3GroupMetadataStoreKey",
     "ZarrV3MetadataField",
     "ZarrV3NamedConfig",
     "is_array_metadata_v2",

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

@@ -321,7 +321,9 @@ def must_understand_fields(self) -> dict[str, ZarrV3ExtensionField]:
     def from_key_value(cls, mapping: Mapping[str, bytes]) -> ZarrV3ArrayMetadata:
         return cls.from_json(load_store_json(mapping, ARRAY_METADATA_STORE_KEY_V3))
 
-    def to_key_value(self, *, indent: int | str | None = None) -> Mapping[str, bytes]:
+    def to_key_value(
+        self, *, indent: int | str | None = None
+    ) -> Mapping[ZarrV3ArrayMetadataStoreKey, bytes]:
         return {ARRAY_METADATA_STORE_KEY_V3: dump_store_json(self.to_json(), indent=indent)}
 
 
@@ -481,12 +483,16 @@ def from_key_value(cls, mapping: Mapping[str, bytes]) -> ZarrV2ArrayMetadata:
             return cls.from_json({**zarray, "attributes": zattrs})
         return cls.from_json(zarray)
 
-    def to_key_value(self, *, indent: int | str | None = None) -> Mapping[str, bytes]:
+    def to_key_value(
+        self, *, indent: int | str | None = None
+    ) -> Mapping[ZarrV2ArrayMetadataStoreKey | ZarrV2AttributesStoreKey, bytes]:
         # Attributes live only in the sibling `.zattrs` file; the `.zarray`
         # document must exclude them. The `.zattrs` key is present exactly
         # when attributes are set (even empty) — UNSET emits no file.
         zarray = {k: v for k, v in self.to_json().items() if k != "attributes"}
-        out = {ARRAY_METADATA_STORE_KEY_V2: dump_store_json(zarray, indent=indent)}
+        out: dict[ZarrV2ArrayMetadataStoreKey | ZarrV2AttributesStoreKey, bytes] = {
+            ARRAY_METADATA_STORE_KEY_V2: dump_store_json(zarray, indent=indent)
+        }
         if self.attributes is not UNSET:
             out[ATTRIBUTES_STORE_KEY_V2] = dump_store_json(self.attributes, indent=indent)
         return out

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

@@ -31,6 +31,7 @@
 
 if TYPE_CHECKING:
     from zarr_metadata._common import JSONValue
+    from zarr_metadata.model._array import ZarrV2AttributesStoreKey
     from zarr_metadata.v2.group import ZarrV2GroupMetadataJSON
     from zarr_metadata.v3.array import ZarrV3ExtensionField
     from zarr_metadata.v3.consolidated import ZarrV3ConsolidatedMetadataJSON
@@ -186,7 +187,9 @@ def must_understand_fields(self) -> dict[str, ZarrV3ExtensionField]:
     def from_key_value(cls, mapping: Mapping[str, bytes]) -> ZarrV3GroupMetadata:
         return cls.from_json(load_store_json(mapping, GROUP_METADATA_STORE_KEY_V3))
 
-    def to_key_value(self, *, indent: int | str | None = None) -> Mapping[str, bytes]:
+    def to_key_value(
+        self, *, indent: int | str | None = None
+    ) -> Mapping[ZarrV3GroupMetadataStoreKey, bytes]:
         return {GROUP_METADATA_STORE_KEY_V3: dump_store_json(self.to_json(), indent=indent)}
 
 
@@ -338,12 +341,16 @@ def from_key_value(cls, mapping: Mapping[str, bytes]) -> ZarrV2GroupMetadata:
             return cls.from_json({**zgroup, "attributes": zattrs})
         return cls.from_json(zgroup)
 
-    def to_key_value(self, *, indent: int | str | None = None) -> Mapping[str, bytes]:
+    def to_key_value(
+        self, *, indent: int | str | None = None
+    ) -> Mapping[ZarrV2GroupMetadataStoreKey | ZarrV2AttributesStoreKey, bytes]:
         # Attributes live only in the sibling `.zattrs` file; the `.zgroup`
         # document must exclude them. The `.zattrs` key is present exactly
         # when attributes are set (even empty) — UNSET emits no file.
         zgroup = {k: v for k, v in self.to_json().items() if k != "attributes"}
-        out = {GROUP_METADATA_STORE_KEY_V2: dump_store_json(zgroup, indent=indent)}
+        out: dict[ZarrV2GroupMetadataStoreKey | ZarrV2AttributesStoreKey, bytes] = {
+            GROUP_METADATA_STORE_KEY_V2: dump_store_json(zgroup, indent=indent)
+        }
         if self.attributes is not UNSET:
             out[ATTRIBUTES_STORE_KEY_V2] = dump_store_json(self.attributes, indent=indent)
         return out
@@ -429,5 +436,7 @@ def from_json(cls, data: object) -> ZarrV2ConsolidatedMetadata:
     def from_key_value(cls, mapping: Mapping[str, bytes]) -> ZarrV2ConsolidatedMetadata:
         return cls.from_json(load_store_json(mapping, CONSOLIDATED_METADATA_STORE_KEY_V2))
 
-    def to_key_value(self, *, indent: int | str | None = None) -> Mapping[str, bytes]:
+    def to_key_value(
+        self, *, indent: int | str | None = None
+    ) -> Mapping[ZarrV2ConsolidatedMetadataStoreKey, bytes]:
         return {CONSOLIDATED_METADATA_STORE_KEY_V2: dump_store_json(self.to_json(), indent=indent)}

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

@@ -5,7 +5,7 @@
 import json
 from collections import UserDict
 from collections.abc import Callable
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, get_args
 
 import pytest
 from typing_extensions import Unpack
@@ -64,6 +64,25 @@ def test_guards_exported_from_package() -> None:
         assert hasattr(zarr_metadata.model, name)
 
 
+def test_store_key_pairs_exported_from_package() -> None:
+    """Each store-key constant is exported together with its Literal type
+    alias, and the pair cannot drift apart."""
+    import zarr_metadata.model as m
+
+    pairs = [
+        ("ARRAY_METADATA_STORE_KEY_V2", "ZarrV2ArrayMetadataStoreKey"),
+        ("ARRAY_METADATA_STORE_KEY_V3", "ZarrV3ArrayMetadataStoreKey"),
+        ("ATTRIBUTES_STORE_KEY_V2", "ZarrV2AttributesStoreKey"),
+        ("GROUP_METADATA_STORE_KEY_V2", "ZarrV2GroupMetadataStoreKey"),
+        ("GROUP_METADATA_STORE_KEY_V3", "ZarrV3GroupMetadataStoreKey"),
+        ("CONSOLIDATED_METADATA_STORE_KEY_V2", "ZarrV2ConsolidatedMetadataStoreKey"),
+    ]
+    for const_name, alias_name in pairs:
+        assert const_name in m.__all__
+        assert alias_name in m.__all__
+        assert (getattr(m, const_name),) == get_args(getattr(m, alias_name))
+
+
 def test_validation_diagnostics_exported_from_package() -> None:
     """The validation-diagnostic types and validators are exported from the package."""
     import zarr_metadata.model