feat: Add separate filepath_default for filepath references

Filepath storage is NOT part of the Object-Augmented Schema - it only
provides references to externally-managed files. Allow separate default
configuration for filepath references vs integrated storage.

Configuration:
- stores.default - for integrated storage (<blob>, <object>, <npy>, <attach>)
- stores.filepath_default - for filepath references (<filepath>)

This allows:
- Integrated storage on S3 or fast filesystem
- Filepath references to acquisition files on NAS or different location

Example:
{
  "stores": {
    "default": "main",
    "filepath_default": "raw_data",
    "main": {
      "protocol": "s3",
      "bucket": "processed-data",
      "location": "lab-project"
    },
    "raw_data": {
      "protocol": "file",
      "location": "/mnt/nas/acquisition"
    }
  }
}

Usage:
- data : <blob>        # Uses stores.default (main)
- arrays : <object>    # Uses stores.default (main)
- raw : <filepath>     # Uses stores.filepath_default (raw_data)
- raw : <filepath@acq> # Explicitly names store (overrides default)

Changes:
- settings.py: Add use_filepath_default parameter to get_store_spec()
- builtin_codecs.py: FilepathCodec uses use_filepath_default=True
- test_settings.py: Add 3 tests for filepath_default behavior
- settings.py: Update template to include filepath_default example

Architectural rationale:
- Hash/schema storage: integrated into OAS, DataJoint manages lifecycle
- Filepath storage: references only, users manage lifecycle
- Different defaults reflect this fundamental distinction

Author: dimitri-yatsenko

src/datajoint/builtin_codecs.py

@@ -815,7 +815,8 @@ def encode(self, value: Any, *, key: dict | None = None, store_name: str | None
         path = str(value)
 
         # Get store spec to check prefix configuration
-        spec = config.get_store_spec(store_name)
+        # Use filepath_default if no store specified (filepath is not part of OAS)
+        spec = config.get_store_spec(store_name, use_filepath_default=True)
 
         # Validate path doesn't use reserved sections (hash and schema)
         path_normalized = path.lstrip("/")

src/datajoint/settings.py

@@ -335,14 +335,20 @@ def convert_path(cls, v: Any) -> Path | None:
             return None
         return Path(v) if not isinstance(v, Path) else v
 
-    def get_store_spec(self, store: str | None = None) -> dict[str, Any]:
+    def get_store_spec(
+        self, store: str | None = None, *, use_filepath_default: bool = False
+    ) -> dict[str, Any]:
         """
         Get configuration for a storage store.
 
         Parameters
         ----------
         store : str, optional
-            Name of the store to retrieve. If None, uses stores.default.
+            Name of the store to retrieve. If None, uses the appropriate default.
+        use_filepath_default : bool, optional
+            If True and store is None, uses stores.filepath_default instead of
+            stores.default. Use for filepath references which are not part of OAS.
+            Default: False (use stores.default for integrated storage).
 
         Returns
         -------
@@ -356,11 +362,23 @@ def get_store_spec(self, store: str | None = None) -> dict[str, Any]:
         """
         # Handle default store
         if store is None:
-            if "default" not in self.stores:
-                raise DataJointError("stores.default is not configured")
-            store = self.stores["default"]
+            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):
-                raise DataJointError("stores.default must be a string")
+                default_key = "filepath_default" if use_filepath_default else "default"
+                raise DataJointError(f"stores.{default_key} must be a string")
 
         # Check store exists
         if store not in self.stores:
@@ -778,13 +796,18 @@ def save_template(
                 },
                 "stores": {
                     "default": "main",
+                    "filepath_default": "raw_data",
                     "main": {
                         "protocol": "file",
                         "location": "/data/my-project/main",
                         "partition_pattern": None,
                         "token_length": 8,
                         "subfolding": None,
                     },
+                    "raw_data": {
+                        "protocol": "file",
+                        "location": "/data/my-project/raw",
+                    },
                 },
                 "loglevel": "INFO",
                 "safemode": True,

tests/unit/test_settings.py

@@ -375,6 +375,72 @@ def test_get_store_spec_no_default_configured(self):
         finally:
             dj.config.stores = original_stores
 
+    def test_get_store_spec_filepath_default(self):
+        """Test filepath_default for filepath references (not part of OAS)."""
+        original_stores = dj.config.stores.copy()
+        try:
+            dj.config.stores["default"] = "integrated"
+            dj.config.stores["filepath_default"] = "raw_data"
+            dj.config.stores["integrated"] = {
+                "protocol": "s3",
+                "endpoint": "s3.amazonaws.com",
+                "bucket": "my-bucket",
+                "location": "processed",
+                "access_key": "xxx",
+                "secret_key": "yyy",
+            }
+            dj.config.stores["raw_data"] = {
+                "protocol": "file",
+                "location": "/data/acquisition",
+            }
+
+            # Regular default for integrated storage
+            spec = dj.config.get_store_spec(None, use_filepath_default=False)
+            assert spec["protocol"] == "s3"
+            assert spec["location"] == "processed"
+
+            # Filepath default for filepath references
+            spec = dj.config.get_store_spec(None, use_filepath_default=True)
+            assert spec["protocol"] == "file"
+            assert spec["location"] == "/data/acquisition"
+        finally:
+            dj.config.stores = original_stores
+
+    def test_get_store_spec_no_filepath_default(self):
+        """Test error when filepath_default not configured but requested."""
+        original_stores = dj.config.stores.copy()
+        try:
+            dj.config.stores["default"] = "integrated"
+            dj.config.stores["integrated"] = {
+                "protocol": "file",
+                "location": "/data/store",
+            }
+            # No filepath_default configured
+
+            with pytest.raises(DataJointError, match="stores.filepath_default is not configured"):
+                dj.config.get_store_spec(None, use_filepath_default=True)
+        finally:
+            dj.config.stores = original_stores
+
+    def test_get_store_spec_explicit_store_ignores_defaults(self):
+        """Test that explicit store name bypasses both defaults."""
+        original_stores = dj.config.stores.copy()
+        try:
+            dj.config.stores["default"] = "store_a"
+            dj.config.stores["filepath_default"] = "store_b"
+            dj.config.stores["store_a"] = {"protocol": "file", "location": "/a"}
+            dj.config.stores["store_b"] = {"protocol": "file", "location": "/b"}
+            dj.config.stores["store_c"] = {"protocol": "file", "location": "/c"}
+
+            # Explicitly naming store_c should work regardless of use_filepath_default
+            spec = dj.config.get_store_spec("store_c", use_filepath_default=False)
+            assert spec["location"] == "/c"
+
+            spec = dj.config.get_store_spec("store_c", use_filepath_default=True)
+            assert spec["location"] == "/c"
+        finally:
+            dj.config.stores = original_stores
+
 
 class TestStoreSecrets:
     """Test loading store credentials from secrets directory."""