fix(#1469): codec-driven GC reference discovery + file-level orphan matching

src/datajoint/__init__.py

@@ -284,7 +284,7 @@ def FreeTable(conn_or_name, full_table_name: str | None = None) -> _FreeTable:
     "diagram": (".diagram", None),  # Return the module itself
     # cli imports click
     "cli": (".cli", "cli"),
-    # gc — exposed lazily so `dj.gc.scan(...)` works as documented in gc.py
+    # gc — exposed lazily so `dj.gc.GarbageCollector(...)` works as documented in gc.py
     # and in the user docs (how-to/garbage-collection.md).
     "gc": (".gc", None),  # Return the module itself
 }

src/datajoint/builtin_codecs/hash.py

@@ -21,7 +21,7 @@ class HashCodec(Codec):
     The database column stores JSON metadata: ``{hash, store, size}``.
     Duplicate content is automatically deduplicated across all tables.
 
-    Deletion: Requires garbage collection via ``dj.gc.collect()``.
+    Deletion: Requires garbage collection via ``dj.gc.GarbageCollector``.
 
     External only - requires @ modifier.
 

src/datajoint/builtin_codecs/npy.py

@@ -272,7 +272,7 @@ class Recording(dj.Manual):
         - Path: ``{schema}/{table}/{pk}/{attribute}.npy``
         - Database column: JSON with ``{path, store, dtype, shape}``
 
-    Deletion: Requires garbage collection via ``dj.gc.collect()``.
+    Deletion: Requires garbage collection via ``dj.gc.GarbageCollector``.
 
     See Also
     --------

src/datajoint/builtin_codecs/object.py

@@ -53,7 +53,7 @@ def make(self, key):
 
             {store_root}/{schema}/{table}/{pk}/{field}/
 
-    Deletion: Requires garbage collection via ``dj.gc.collect()``.
+    Deletion: Requires garbage collection via ``dj.gc.GarbageCollector``.
 
     Comparison with hash-addressed::
 

src/datajoint/builtin_codecs/schema.py

@@ -114,7 +114,7 @@ def _build_path(
         Build schema-addressed storage path.
 
         Constructs a path that mirrors the database schema structure:
-        ``{schema}/{table}/{pk_values}/{field}{ext}``
+        ``{schema_prefix}/{schema}/{table}/{pk_values}/{field}{ext}``
 
         Supports partitioning if configured in the store.
 
@@ -150,6 +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["schema_prefix"]  # always present: settings applies the default
 
         return build_object_path(
             schema=schema,
@@ -159,6 +160,7 @@ def _build_path(
             ext=ext,
             partition_pattern=partition_pattern,
             token_length=token_length,
+            schema_prefix=schema_prefix,
         )
 
     def _get_backend(self, store_name: str | None = None, config=None):

src/datajoint/codecs.py

@@ -38,6 +38,7 @@ class MyTable(dj.Manual):
 
 from __future__ import annotations
 
+import json
 import logging
 from abc import ABC, abstractmethod
 from typing import Any
@@ -219,6 +220,45 @@ def validate(self, value: Any) -> None:
         """
         pass
 
+    def referenced_paths(self, stored: Any) -> list[tuple[str, str | None]]:
+        """
+        Return the external store paths this stored value references.
+
+        Garbage collection and delete-time cleanup call this on the *stored*
+        (encoded) representation of a column value — the JSON/dict already in
+        the database — so discovery stays metadata-only (no download or decode).
+
+        The default recognizes DataJoint's standard external-storage metadata:
+        a dict (or JSON string) carrying a ``path`` and optional ``store``. This
+        covers hash-addressed (``<hash@>``/``<blob@>``/``<attach@>``) and
+        schema-addressed (``<object@>``/``<npy@>`` and any :class:`SchemaCodec`
+        subclass) storage with no extra work, and returns an empty list for
+        values that are not externally stored (e.g. in-table ``<blob>``).
+
+        Override only if your codec stores external references in a non-standard
+        shape. Returning the paths here is what lets garbage collection see a
+        custom codec's files as *referenced* rather than orphaned (see #1469).
+
+        Parameters
+        ----------
+        stored : any
+            The stored (encoded) value as read from the database column.
+
+        Returns
+        -------
+        list[tuple[str, str | None]]
+            ``(path, store_name)`` for each external artifact referenced.
+        """
+        value = stored
+        if isinstance(value, str):
+            try:
+                value = json.loads(value)
+            except (json.JSONDecodeError, TypeError, ValueError):
+                return []
+        if isinstance(value, dict) and "path" in value:
+            return [(value["path"], value.get("store"))]
+        return []
+
     def __repr__(self) -> str:
         return f"<{self.__class__.__name__}(name={self.name!r})>"