fix: record the resolved store name; an empty name builds the default collector

GarbageCollector(schema, store="") built a collector whose store stayed "",
so _references matched no reference and collect(dry_run=False) would have
deleted every file in the default store. An empty name now builds the default
collector, as None does.

Codecs recorded the store name as declared, so a bare-@ reference stored ""
and followed stores.default: re-pointing the default would break reads, and a
collector bound to the old store by name would delete live files. Codecs now
record the resolved name (new Config.resolve_store_name, which get_store_spec
also uses), so each object stays with the store it was written to. Bare @
could not be written before this change, so no stored metadata has an empty
name; metadata that records none still means the current default.

Author: dimitri-yatsenko

src/datajoint/builtin_codecs/filepath.py

@@ -164,7 +164,7 @@ def encode(
 
         return {
             "path": path,
-            "store": store_name,
+            "store": config.resolve_store_name(store_name, use_filepath_default=True),
             "size": size,
             "is_dir": is_dir,
             "timestamp": datetime.now(timezone.utc).isoformat(),

src/datajoint/builtin_codecs/npy.py

@@ -356,7 +356,7 @@ def encode(
         # Return metadata (includes numpy-specific shape/dtype)
         return {
             "path": path,
-            "store": store_name,
+            "store": config.resolve_store_name(store_name),
             "dtype": str(value.dtype),
             "shape": list(value.shape),
         }

src/datajoint/builtin_codecs/object.py

@@ -168,7 +168,7 @@ def encode(
         timestamp = datetime.now(timezone.utc)
         metadata = {
             "path": path,
-            "store": store_name,
+            "store": config.resolve_store_name(store_name),
             "size": size,
             "ext": ext,
             "is_dir": is_dir,

src/datajoint/builtin_codecs/schema.py

@@ -66,7 +66,7 @@ def encode(self, value, *, key=None, context=None, store_name=None):
                 )
                 backend = self._get_backend(store_name, config=config)
                 backend.put_buffer(serialize(value), path)
-                return {"path": path, "store": store_name, ...}
+                return {"path": path, "store": config.resolve_store_name(store_name), ...}
 
             def decode(self, stored, *, key=None, context=None):
                 config = self._codec_config(key, context)

src/datajoint/gc.py

@@ -113,10 +113,13 @@ def __init__(self, *schemas: "Schema", store: str | None = None, config=None) ->
         if not schemas:
             raise DataJointError("At least one schema must be provided")
         self.schemas = schemas
-        self.store = store
+        # An empty name (the bare ``@`` form) means the default store, as None
+        # does. Kept as "", it would match no reference in _references, and every
+        # stored file would look orphaned.
+        self.store = store or None
         self.config = config if config is not None else schemas[0].connection._config
-        # References written with the bare ``@`` form record an empty store name
-        # (older metadata may record none); both mean the default store.
+        # References record the resolved store name. Metadata written before
+        # that may record an empty name or none; both mean the default store.
         self._default_store = self.config.stores.get("default")
         # Resolve the store eagerly: validates it exists and pins the backend
         # and section prefixes for this collector's lifetime (one store only).

src/datajoint/hash_registry.py

@@ -250,7 +250,7 @@ def put_hash(
         "hash": content_hash,
         "path": path,  # Always stored for retrieval
         "schema": schema_name,
-        "store": store_name,
+        "store": config.resolve_store_name(store_name),
         "size": len(data),
     }
 

src/datajoint/settings.py

@@ -447,6 +447,58 @@ def convert_path(cls, v: Any) -> Path | None:
             return None
         return Path(v) if not isinstance(v, Path) else v
 
+    def resolve_store_name(self, store: str | None = None, *, use_filepath_default: bool = False) -> str:
+        """
+        Name the configured store that a store reference resolves to.
+
+        An empty or missing name means the default store: ``stores.default``,
+        or ``stores.filepath_default`` for filepath references. Codecs record
+        the resolved name in their metadata, so a stored object stays tied to
+        the store it was written to even if the default is later re-pointed.
+
+        Parameters
+        ----------
+        store : str, optional
+            Store name as declared. ``""`` (the bare ``@`` form) and None both
+            mean the default store.
+        use_filepath_default : bool, optional
+            If True, resolve the default to stores.filepath_default instead of
+            stores.default. Default: False.
+
+        Returns
+        -------
+        str
+            Name of a key in ``stores``.
+
+        Raises
+        ------
+        DataJointError
+            If the default store is needed but not configured.
+        """
+        if store:
+            return store
+        # An empty name is the bare ``@`` form (``<npy@>``, ``<object@>``, ...),
+        # which the declaration keeps as "" so the codec can tell "store
+        # requested" from "no store"; it means the default store.
+        if use_filepath_default:
+            # Filepath references use separate default (not part of OAS)
+            if "filepath_default" not in self.stores:
+                raise DataJointError(
+                    "stores.filepath_default is not configured. "
+                    "Set stores.filepath_default or specify store explicitly with <filepath@store>"
+                )
+            store = self.stores["filepath_default"]
+        else:
+            # Integrated storage (hash, schema) uses stores.default
+            if "default" not in self.stores:
+                raise DataJointError("stores.default is not configured")
+            store = self.stores["default"]
+
+        if not isinstance(store, str):
+            default_key = "filepath_default" if use_filepath_default else "default"
+            raise DataJointError(f"stores.{default_key} must be a string")
+        return store
+
     def get_store_spec(self, store: str | None = None, *, use_filepath_default: bool = False) -> dict[str, Any]:
         """
         Get configuration for a storage store.
@@ -470,27 +522,7 @@ def get_store_spec(self, store: str | None = None, *, use_filepath_default: bool
         DataJointError
             If store is not configured or has invalid config.
         """
-        # Handle default store. An empty name is the bare ``@`` form (``<npy@>``,
-        # ``<object@>``, ...), which the declaration keeps as "" so the codec can
-        # tell "store requested" from "no store"; it means the default store.
-        if not store:
-            if use_filepath_default:
-                # Filepath references use separate default (not part of OAS)
-                if "filepath_default" not in self.stores:
-                    raise DataJointError(
-                        "stores.filepath_default is not configured. "
-                        "Set stores.filepath_default or specify store explicitly with <filepath@store>"
-                    )
-                store = self.stores["filepath_default"]
-            else:
-                # Integrated storage (hash, schema) uses stores.default
-                if "default" not in self.stores:
-                    raise DataJointError("stores.default is not configured")
-                store = self.stores["default"]
-
-            if not isinstance(store, str):
-                default_key = "filepath_default" if use_filepath_default else "default"
-                raise DataJointError(f"stores.{default_key} must be a string")
+        store = self.resolve_store_name(store, use_filepath_default=use_filepath_default)
 
         # Check store exists
         if store not in self.stores:

tests/integration/test_gc.py

@@ -2,6 +2,7 @@
 Tests for garbage collection (gc.py).
 """
 
+import json
 from contextlib import ExitStack
 from unittest.mock import MagicMock, patch
 
@@ -448,17 +449,57 @@ def test_roundtrip(self, schema_bare):
         assert np.array_equal(np.asarray((GcBareNpyTest & "rid=1").fetch1("waveform")), waveform)
 
     def test_collecting_the_default_store_by_name_keeps_bare_at_files(self, schema_bare):
-        """A collector bound to the default store by name must count bare-@ references.
+        """A collector bound to the default store by name must count bare-@ references."""
+        waveform = np.arange(64, dtype="float32")
+        GcBareNpyTest.insert1({"rid": 1, "waveform": waveform})
+        path = (GcBareNpyTest & "rid=1").fetch1("waveform").path
+
+        stats = _gc(schema_bare, store="local").collect(dry_run=False)
+
+        assert stats["schema_paths_referenced"] >= 1
+        assert not any(orphan.endswith(path) for orphan in stats["orphaned_schema_paths"])
+        assert np.array_equal(np.asarray((GcBareNpyTest & "rid=1").fetch1("waveform")), waveform)
+
+    def test_metadata_records_the_resolved_store(self, schema_bare):
+        """A bare-@ write records the store it went to, not the empty name."""
+        GcBareNpyTest.insert1({"rid": 1, "waveform": np.arange(8, dtype="float32")})
+
+        (raw,) = (GcBareNpyTest & "rid=1").proj("waveform").cursor(as_dict=True)
+        metadata = raw["waveform"]
+        if isinstance(metadata, str):  # MySQL returns JSON as text, PostgreSQL as a dict
+            metadata = json.loads(metadata)
+
+        assert metadata["store"] == "local"
+
+    def test_repointing_the_default_store_keeps_existing_files(self, schema_bare):
+        """Re-pointing stores.default leaves existing bare-@ objects readable and collected.
 
-        Their metadata records an empty store name; if the scan compared it to "local"
-        literally, the files would be reported as orphans and deleted.
+        References record "local", so after the default moves to "raw" they still read
+        from "local", and a collector bound to "local" still counts them.
         """
         waveform = np.arange(64, dtype="float32")
         GcBareNpyTest.insert1({"rid": 1, "waveform": waveform})
         path = (GcBareNpyTest & "rid=1").fetch1("waveform").path
 
+        dj.config.stores["default"] = "raw"
+        assert np.array_equal(np.asarray((GcBareNpyTest & "rid=1").fetch1("waveform")), waveform)
+
         stats = _gc(schema_bare, store="local").collect(dry_run=False)
 
+        assert not any(orphan.endswith(path) for orphan in stats["orphaned_schema_paths"])
+        assert np.array_equal(np.asarray((GcBareNpyTest & "rid=1").fetch1("waveform")), waveform)
+
+    def test_empty_store_name_is_the_default_collector(self, schema_bare):
+        """``store=""`` builds the same collector as no store, and deletes no live file."""
+        waveform = np.arange(64, dtype="float32")
+        GcBareNpyTest.insert1({"rid": 1, "waveform": waveform})
+        path = (GcBareNpyTest & "rid=1").fetch1("waveform").path
+
+        collector = _gc(schema_bare, store="")
+        assert collector.store is None
+
+        stats = collector.collect(dry_run=False)
+
         assert stats["schema_paths_referenced"] >= 1
         assert not any(orphan.endswith(path) for orphan in stats["orphaned_schema_paths"])
         assert np.array_equal(np.asarray((GcBareNpyTest & "rid=1").fetch1("waveform")), waveform)

tests/unit/test_settings.py

@@ -434,6 +434,35 @@ def test_get_store_spec_empty_name_is_filepath_default(self):
         finally:
             dj.config.stores = original_stores
 
+    def test_resolve_store_name(self):
+        """An empty or missing name resolves to the configured default; a name to itself."""
+        original_stores = dj.config.stores.copy()
+        try:
+            dj.config.stores = {
+                "default": "main",
+                "filepath_default": "raw_data",
+                "main": {"protocol": "file", "location": "/tmp/main"},
+                "raw_data": {"protocol": "file", "location": "/data/acquisition"},
+                "archive": {"protocol": "file", "location": "/tmp/archive"},
+            }
+            assert dj.config.resolve_store_name("") == "main"
+            assert dj.config.resolve_store_name(None) == "main"
+            assert dj.config.resolve_store_name("archive") == "archive"
+            assert dj.config.resolve_store_name("", use_filepath_default=True) == "raw_data"
+            assert dj.config.resolve_store_name("archive", use_filepath_default=True) == "archive"
+        finally:
+            dj.config.stores = original_stores
+
+    def test_resolve_store_name_without_default_raises(self):
+        """The bare ``@`` form with no stores.default configured is an error."""
+        original_stores = dj.config.stores.copy()
+        try:
+            dj.config.stores = {"main": {"protocol": "file", "location": "/tmp/main"}}
+            with pytest.raises(DataJointError, match="stores.default is not configured"):
+                dj.config.resolve_store_name("")
+        finally:
+            dj.config.stores = original_stores
+
     def test_get_store_spec_no_default_configured(self):
         """Test error when stores.default is not configured."""
         original_stores = dj.config.stores.copy()