refactor(storage): drop builder prefix fallbacks — settings is the single source

Review finding: build_hash_path/build_object_path carried default prefix
parameters (DEFAULT_HASH_PREFIX/DEFAULT_SCHEMA_PREFIX) duplicating the
defaults that settings already applies. _apply_common_store_defaults runs for
EVERY store spec — built-in and plugin protocols alike — before
get_store_spec returns, so the fallbacks were dead code and a second place
for the default to drift.

The prefixes are now required keyword-only parameters; both constants are
deleted; all production callers index the spec directly (spec['hash_prefix'] /
spec['schema_prefix']) with a loud KeyError, rather than a silent wrong-layout
write, as the failure mode for any spec that bypassed get_store_spec. Direct
builder calls in tests pass the prefix explicitly, which is the honest
contract.

Suites: hash-storage/object/unit 377 passed; gc/npy/chaining green.

Author: dimitri-yatsenko

src/datajoint/builtin_codecs/schema.py

@@ -150,7 +150,7 @@ def _build_path(
         spec = config.get_store_spec(store_name)
         partition_pattern = spec.get("partition_pattern")
         token_length = spec.get("token_length", 8)
-        schema_prefix = spec.get("schema_prefix", "_schema")
+        schema_prefix = spec["schema_prefix"]  # always present: settings applies the default
 
         return build_object_path(
             schema=schema,

src/datajoint/gc.py

@@ -41,7 +41,7 @@
 import logging
 from typing import TYPE_CHECKING, Any
 
-from .hash_registry import DEFAULT_HASH_PREFIX, delete_path, get_store_backend
+from .hash_registry import delete_path, get_store_backend
 from .errors import DataJointError
 
 if TYPE_CHECKING:
@@ -286,7 +286,7 @@ def list_stored_hashes(store_name: str | None = None, config=None) -> dict[str,
     # value remain readable (their metadata stores full paths) but are not
     # candidates for reclamation until the setting is restored.
     _spec = config.get_store_spec(store_name)
-    hash_prefix = _spec.get("hash_prefix", DEFAULT_HASH_PREFIX).strip("/") + "/"
+    hash_prefix = _spec["hash_prefix"].strip("/") + "/"  # settings applies the "_hash" default
     # Base32 pattern: 26 lowercase alphanumeric chars
     base32_pattern = re.compile(r"^[a-z2-7]{26}$")
 
@@ -363,7 +363,7 @@ def list_schema_paths(store_name: str | None = None, config=None) -> dict[str, i
     _spec = config.get_store_spec(store_name)
     _fp = _spec.get("filepath_prefix")
     filepath_prefix = (_fp.strip("/") + "/") if _fp else None
-    _hp = _spec.get("hash_prefix", DEFAULT_HASH_PREFIX).strip("/")
+    _hp = _spec["hash_prefix"].strip("/")  # settings applies the "_hash" default
     hash_section = _hp + "/" if _hp else None
 
     try:

src/datajoint/hash_registry.py

@@ -48,14 +48,6 @@
 logger = logging.getLogger(__name__.split(".")[0])
 
 
-# Default section prefix for hash-addressed storage. The authoritative value
-# is the per-store `hash_prefix` setting (default "_hash", see
-# settings.get_store_spec and docs/how-to/configure-storage) — writers, GC,
-# and <filepath@> validation all consume the same setting so the layout can
-# be relocated per store without the components drifting apart.
-DEFAULT_HASH_PREFIX = "_hash"
-
-
 def compute_hash(data: bytes) -> str:
     """
     Compute Base32-encoded MD5 hash of content.
@@ -105,7 +97,8 @@ def build_hash_path(
     content_hash: str,
     schema_name: str,
     subfolding: tuple[int, ...] | None = None,
-    hash_prefix: str = DEFAULT_HASH_PREFIX,
+    *,
+    hash_prefix: str,
 ) -> str:
     """
     Build the storage path for hash-addressed storage.
@@ -126,9 +119,10 @@ def build_hash_path(
         Database/schema name for isolation.
     subfolding : tuple[int, ...], optional
         Subfolding pattern from store config. None means flat (no subfolding).
-    hash_prefix : str, optional
-        Section prefix from the store's ``hash_prefix`` setting
-        (default ``"_hash"``).
+    hash_prefix : str
+        Section prefix from the store's ``hash_prefix`` setting. There is no
+        fallback here by design: settings (``get_store_spec``) is the single
+        source of the ``"_hash"`` default, applied to every store spec.
 
     Returns
     -------
@@ -240,7 +234,7 @@ def put_hash(
         content_hash,
         schema_name,
         subfolding,
-        hash_prefix=spec.get("hash_prefix", DEFAULT_HASH_PREFIX),
+        hash_prefix=spec["hash_prefix"],  # always present: settings applies the default
     )
 
     backend = get_store_backend(store_name, config=config)

src/datajoint/staged_insert.py

@@ -120,7 +120,7 @@ def _resolve_field(self, field: str, ext: str) -> tuple[str, "StorageBackend"]:
             ext=ext if ext else None,
             partition_pattern=partition_pattern,
             token_length=token_length,
-            schema_prefix=spec.get("schema_prefix", "_schema"),
+            schema_prefix=spec["schema_prefix"],  # always present: settings applies the default
         )
 
         self._staged_objects[field] = {

src/datajoint/storage.py

@@ -188,12 +188,6 @@ def encode_pk_value(value: Any) -> str:
     return s
 
 
-# Default section prefix for schema-addressed storage. The authoritative value
-# is the per-store `schema_prefix` setting (default "_schema", see
-# settings.get_store_spec and docs/how-to/configure-storage).
-DEFAULT_SCHEMA_PREFIX = "_schema"
-
-
 def build_object_path(
     schema: str,
     table: str,
@@ -202,7 +196,8 @@ def build_object_path(
     ext: str | None,
     partition_pattern: str | None = None,
     token_length: int = 8,
-    schema_prefix: str = DEFAULT_SCHEMA_PREFIX,
+    *,
+    schema_prefix: str,
 ) -> tuple[str, str]:
     """
     Build the storage path for an object attribute.
@@ -223,9 +218,10 @@ def build_object_path(
         Partition pattern with ``{attr}`` placeholders.
     token_length : int, optional
         Length of random token suffix. Default 8.
-    schema_prefix : str, optional
-        Section prefix from the store's ``schema_prefix`` setting
-        (default ``"_schema"``).
+    schema_prefix : str
+        Section prefix from the store's ``schema_prefix`` setting. No fallback
+        by design: settings (``get_store_spec``) is the single source of the
+        ``"_schema"`` default, applied to every store spec.
 
     Returns
     -------

tests/integration/test_hash_storage.py

@@ -58,33 +58,33 @@ class TestBuildHashPath:
     def test_builds_flat_path(self):
         """Test that path is built as _hash/{schema}/{hash}."""
         test_hash = "abcdefghijklmnopqrstuvwxyz"[:26]  # 26 char base32
-        result = build_hash_path(test_hash, "my_schema")
+        result = build_hash_path(test_hash, "my_schema", hash_prefix="_hash")
 
         assert result == f"_hash/my_schema/{test_hash}"
 
     def test_builds_subfolded_path(self):
         """Test path with subfolding."""
         test_hash = "abcdefghijklmnopqrstuvwxyz"[:26]
-        result = build_hash_path(test_hash, "my_schema", subfolding=(2, 2))
+        result = build_hash_path(test_hash, "my_schema", subfolding=(2, 2), hash_prefix="_hash")
 
         assert result == f"_hash/my_schema/ab/cd/{test_hash}"
 
     def test_rejects_invalid_hash(self):
         """Test that invalid hash raises error."""
         with pytest.raises(DataJointError, match="Invalid content hash"):
-            build_hash_path("not-a-hash", "my_schema")
+            build_hash_path("not-a-hash", "my_schema", hash_prefix="_hash")
 
         with pytest.raises(DataJointError, match="Invalid content hash"):
-            build_hash_path("a" * 64, "my_schema")  # Too long
+            build_hash_path("a" * 64, "my_schema", hash_prefix="_hash")  # Too long
 
         with pytest.raises(DataJointError, match="Invalid content hash"):
-            build_hash_path("ABCDEFGHIJKLMNOPQRSTUVWXYZ"[:26], "my_schema")  # Uppercase
+            build_hash_path("ABCDEFGHIJKLMNOPQRSTUVWXYZ"[:26], "my_schema", hash_prefix="_hash")  # Uppercase
 
     def test_real_hash_path(self):
         """Test path building with a real computed hash."""
         data = b"test content"
         content_hash = compute_hash(data)
-        path = build_hash_path(content_hash, "test_schema")
+        path = build_hash_path(content_hash, "test_schema", hash_prefix="_hash")
 
         # Verify structure: _hash/{schema}/{hash}
         parts = path.split("/")

tests/integration/test_object.py

@@ -80,6 +80,7 @@ def test_build_object_path_basic(self):
             field="data_file",
             primary_key={"id": 123},
             ext=".dat",
+            schema_prefix="_schema",
         )
         assert "myschema" in path
         assert "MyTable" in path
@@ -96,6 +97,7 @@ def test_build_object_path_no_extension(self):
             field="data_folder",
             primary_key={"id": 456},
             ext=None,
+            schema_prefix="_schema",
         )
         assert not path.endswith(".")
         assert "data_folder_" in path
@@ -108,6 +110,7 @@ def test_build_object_path_multiple_pk(self):
             field="raw_data",
             primary_key={"subject_id": 1, "session_id": 2},
             ext=".zarr",
+            schema_prefix="_schema",
         )
         assert "subject_id=1" in path
         assert "session_id=2" in path
@@ -121,6 +124,7 @@ def test_build_object_path_with_partition(self):
             primary_key={"subject_id": 1, "session_id": 2},
             ext=".dat",
             partition_pattern="{subject_id}",
+            schema_prefix="_schema",
         )
         # subject_id should be at the beginning due to partition
         # section prefix first, then partition attrs (schema_prefix default "_schema")