chore: import upstream snapshot with attribution

python/mirage/core/databricks_volume/__init__.py

@@ -0,0 +1,13 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========

python/mirage/core/databricks_volume/_helpers.py

@@ -0,0 +1,39 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.types import PathSpec
+from mirage.utils.key_prefix import mount_key, mount_prefix_of
+
+
+def ensure_path_spec(path: PathSpec | str) -> PathSpec:
+    if isinstance(path, PathSpec):
+        return path
+    return PathSpec.from_str_path(path)
+
+
+def parent_path(path: PathSpec | str) -> PathSpec:
+    path = ensure_path_spec(path)
+    prefix = mount_prefix_of(path.virtual, path.resource_path)
+    stripped = path.mount_path.rstrip("/")
+    parent_relative = stripped.rsplit("/", 1)[0] if "/" in stripped else "/"
+    if not parent_relative.startswith("/"):
+        parent_relative = "/" + parent_relative
+    if prefix:
+        original = prefix.rstrip("/")
+        if parent_relative != "/":
+            original += parent_relative
+    else:
+        original = parent_relative
+    return PathSpec.from_str_path(original or "/",
+                                  mount_key(original or "/", prefix))

python/mirage/core/databricks_volume/copy.py

@@ -0,0 +1,111 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+from io import BytesIO
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import ensure_path_spec
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.read import read_bytes
+from mirage.core.databricks_volume.stat import stat
+from mirage.core.databricks_volume.write import write_bytes
+from mirage.types import FileType, PathSpec
+
+
+def _download_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> bytes:
+    response = accessor.files.download(remote_path)
+    contents = getattr(response, "contents", response)
+    if hasattr(contents, "read"):
+        return contents.read()
+    return bytes(contents)
+
+
+def _upload_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+    data: bytes,
+) -> None:
+    accessor.files.upload(remote_path, BytesIO(data), overwrite=True)
+
+
+def _create_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.create_directory(remote_path)
+
+
+def _list_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> list:
+    return list(accessor.files.list_directory_contents(remote_path))
+
+
+def _copy_tree_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_src: str,
+    remote_dst: str,
+) -> None:
+    _create_directory_sync(accessor, remote_dst)
+    for entry in _list_directory_sync(accessor, remote_src):
+        name = entry.path.rstrip("/").rsplit("/", 1)[-1]
+        child_dst = remote_dst.rstrip("/") + "/" + name
+        if getattr(entry, "is_directory", False):
+            _copy_tree_sync(accessor, entry.path, child_dst)
+        else:
+            _upload_sync(accessor, child_dst,
+                         _download_sync(accessor, entry.path))
+
+
+async def copy(
+    accessor: DatabricksVolumeAccessor,
+    src: PathSpec,
+    dst: PathSpec,
+    index: IndexCacheStore = None,
+    recursive: bool = False,
+) -> None:
+    src = ensure_path_spec(src)
+    dst = ensure_path_spec(dst)
+    src_stat = await stat(accessor, src, index)
+    # Same-path guard runs after stat (and the non-recursive directory check)
+    # so a missing source or `cp` of a directory still raises.
+    same_path = backend_path(accessor.config,
+                             src) == backend_path(accessor.config, dst)
+    if src_stat.type == FileType.DIRECTORY:
+        if not recursive:
+            raise IsADirectoryError(src.virtual)
+        if same_path:
+            return
+        remote_src = backend_path(accessor.config, src)
+        remote_dst = backend_path(accessor.config, dst)
+        if remote_dst.startswith(remote_src + "/"):
+            # Copying a directory into its own subtree creates the destination
+            # inside the source, so the walk would descend into the fresh copy
+            # forever. Refuse before any create_directory/upload.
+            raise ValueError(f"cannot copy a directory, '{src.virtual}', "
+                             f"into itself, '{dst.virtual}'")
+        await asyncio.to_thread(_copy_tree_sync, accessor, remote_src,
+                                remote_dst)
+        return
+    if same_path:
+        # Copying a file onto itself would re-upload it; skip.
+        return
+    data = await read_bytes(accessor, src, index)
+    await write_bytes(accessor, dst, data, index)

python/mirage/core/databricks_volume/create.py

@@ -0,0 +1,26 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume.write import write_bytes
+from mirage.types import PathSpec
+
+
+async def create(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> None:
+    await write_bytes(accessor, path, b"", index)

python/mirage/core/databricks_volume/errors.py

@@ -0,0 +1,24 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+
+def is_not_found(exc: Exception) -> bool:
+    status_code = getattr(exc, "status_code", None)
+    if status_code == 404:
+        return True
+    error_code = getattr(exc, "error_code", None)
+    if error_code in {"RESOURCE_DOES_NOT_EXIST", "NOT_FOUND"}:
+        return True
+    message = str(exc).lower()
+    return "not found" in message or "does not exist" in message

python/mirage/core/databricks_volume/exists.py

@@ -0,0 +1,25 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.core.databricks_volume.stat import stat
+from mirage.types import PathSpec
+
+
+async def exists(accessor: DatabricksVolumeAccessor, path: PathSpec) -> bool:
+    try:
+        await stat(accessor, path)
+        return True
+    except FileNotFoundError:
+        return False

python/mirage/core/databricks_volume/glob.py

@@ -0,0 +1,29 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.commands.builtin.constants import SCOPE_ERROR
+from mirage.core.databricks_volume.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+
+
+async def resolve_glob(
+    accessor: DatabricksVolumeAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/databricks_volume/mkdir.py

@@ -0,0 +1,60 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import (ensure_path_spec,
+                                                    parent_path)
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.exists import exists
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.stat import stat
+from mirage.types import FileType, PathSpec
+from mirage.utils.errors import enoent, enotdir
+
+
+def _create_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.create_directory(remote_path)
+
+
+async def mkdir(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+    parents: bool = False,
+) -> None:
+    path = ensure_path_spec(path)
+    remote_path = backend_path(accessor.config, path)
+    if parents:
+        await asyncio.to_thread(_create_directory_sync, accessor, remote_path)
+        return
+    if await exists(accessor, path):
+        raise FileExistsError(path.virtual)
+    parent = parent_path(path)
+    parent_stat = await stat(accessor, parent, index)
+    if parent_stat.type != FileType.DIRECTORY:
+        raise enotdir(path)
+    try:
+        await asyncio.to_thread(_create_directory_sync, accessor, remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    await invalidate_after_write(path)

python/mirage/core/databricks_volume/path.py

@@ -0,0 +1,72 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import posixpath
+
+from mirage.resource.databricks_volume.config import DatabricksVolumeConfig
+from mirage.types import PathSpec
+
+
+def volume_root(config: DatabricksVolumeConfig) -> str:
+    return posixpath.join("/Volumes", config.catalog, config.schema_name,
+                          config.volume)
+
+
+def _assert_inside_root(root: str, path: str, message: str) -> None:
+    if path == root or path.startswith(root + "/"):
+        return
+    raise ValueError(message)
+
+
+def configured_root(config: DatabricksVolumeConfig) -> str:
+    root_relative = config.root_path.strip("/")
+    if root_relative:
+        return posixpath.normpath(
+            posixpath.join(volume_root(config), root_relative))
+    return posixpath.normpath(volume_root(config))
+
+
+def backend_path(config: DatabricksVolumeConfig, path: PathSpec | str) -> str:
+    if isinstance(path, PathSpec):
+        raw = path.mount_path
+    else:
+        raw = path
+    relative = raw.strip("/")
+    root = configured_root(config)
+    parts = [root]
+    if relative:
+        parts.append(relative)
+    remote_path = posixpath.normpath(posixpath.join(*parts))
+    _assert_inside_root(
+        root,
+        remote_path,
+        f"path escapes Databricks volume root: {raw}",
+    )
+    return remote_path
+
+
+def virtual_path(config: DatabricksVolumeConfig,
+                 backend: str,
+                 prefix: str = "") -> str:
+    root = configured_root(config)
+    remote_path = posixpath.normpath(backend)
+    _assert_inside_root(
+        root,
+        remote_path,
+        f"backend path is outside Databricks volume root: {backend}",
+    )
+    relative = remote_path.removeprefix(root).strip("/")
+    path = "/" + relative if relative else "/"
+    return prefix.rstrip(
+        "/") + path if prefix and path != "/" else prefix or path

python/mirage/core/databricks_volume/read.py

@@ -0,0 +1,112 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import time
+from urllib.parse import quote
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.observe.context import record
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+def _read_response_bytes(response) -> bytes:
+    if isinstance(response, dict):
+        contents = response.get("contents", response)
+    else:
+        contents = getattr(response, "contents", response)
+    if isinstance(contents, bytes):
+        return contents
+    if hasattr(contents, "read"):
+        return contents.read()
+    return bytes(contents)
+
+
+def _range_header(offset: int, size: int | None) -> str | None:
+    if offset < 0:
+        raise ValueError("offset must be non-negative")
+    if size is not None and size < 0:
+        raise ValueError("size must be non-negative")
+    if offset == 0 and size is None:
+        return None
+    if size is None:
+        return f"bytes={offset}-"
+    return f"bytes={offset}-{offset + size - 1}"
+
+
+def _download_bytes_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+    range_header: str | None,
+) -> bytes:
+    if range_header is None:
+        return _read_response_bytes(accessor.files.download(remote_path))
+    headers = {
+        "Accept": "application/octet-stream",
+        "Range": range_header,
+    }
+    cfg = getattr(accessor.client.api_client, "_cfg", None)
+    workspace_id = getattr(cfg, "workspace_id", None)
+    if workspace_id:
+        headers["X-Databricks-Org-Id"] = workspace_id
+    response = accessor.client.api_client.do(
+        "GET",
+        f"/api/2.0/fs/files{quote(remote_path)}",
+        headers=headers,
+        response_headers=[
+            "content-length",
+            "content-range",
+            "accept-ranges",
+            "content-type",
+            "last-modified",
+        ],
+        raw=True,
+    )
+    return _read_response_bytes(response)
+
+
+async def read_bytes(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+    offset: int = 0,
+    size: int | None = None,
+) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    remote_path = backend_path(accessor.config, path)
+    start_ms = int(time.monotonic() * 1000)
+    if size == 0:
+        record("read", virtual, "databricks_volume", 0, start_ms)
+        return b""
+    try:
+        data = await asyncio.to_thread(
+            _download_bytes_sync,
+            accessor,
+            remote_path,
+            _range_header(offset, size),
+        )
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    record("read", virtual, "databricks_volume", len(data), start_ms)
+    return data

python/mirage/core/databricks_volume/readdir.py

@@ -0,0 +1,90 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import logging
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore, IndexEntry
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path, virtual_path
+from mirage.core.databricks_volume.stat import modified_to_iso
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_prefix_of
+
+logger = logging.getLogger(__name__)
+SCOPE_ERROR = 10_000
+
+
+def _list_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> list[object]:
+    return list(accessor.files.list_directory_contents(remote_path))
+
+
+async def readdir(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore,
+) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    list_path = path.dir if path.pattern else path
+    virtual_key = list_path.virtual.rstrip("/") or "/"
+    listing = await index.list_dir(virtual_key)
+    if listing.entries is not None:
+        return listing.entries
+    remote_path = backend_path(accessor.config, list_path)
+    try:
+        entries = await asyncio.to_thread(
+            _list_directory_sync,
+            accessor,
+            remote_path,
+        )
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(list_path) from exc
+        raise
+    pairs = sorted(
+        (virtual_path(accessor.config, entry.path,
+                      mount_prefix_of(path.virtual, path.resource_path)),
+         entry) for entry in entries)
+    names = [name for name, _ in pairs]
+    if len(names) > SCOPE_ERROR:
+        logger.warning(
+            "databricks_volume readdir: %s returned %d entries (limit %d)",
+            virtual_key,
+            len(names),
+            SCOPE_ERROR,
+        )
+    index_entries = []
+    for full_path, entry in pairs:
+        name = full_path.rstrip("/").rsplit("/", 1)[-1]
+        resource_type = "folder" if getattr(entry, "is_directory",
+                                            False) else "file"
+        remote_time = modified_to_iso(getattr(entry, "last_modified", None))
+        index_entries.append((name,
+                              IndexEntry(
+                                  id=full_path,
+                                  name=name,
+                                  resource_type=resource_type,
+                                  size=getattr(entry, "file_size", None),
+                                  remote_time=remote_time or "",
+                              )))
+    await index.set_dir(virtual_key, index_entries)
+    return names

python/mirage/core/databricks_volume/rename.py

@@ -0,0 +1,60 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import (invalidate_after_unlink,
+                                  invalidate_after_write)
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import ensure_path_spec
+from mirage.core.databricks_volume.copy import copy
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.rm import rm_recursive
+from mirage.core.databricks_volume.stat import stat
+from mirage.core.databricks_volume.unlink import unlink
+from mirage.types import FileType, PathSpec
+
+
+async def rename(
+    accessor: DatabricksVolumeAccessor,
+    src: PathSpec,
+    dst: PathSpec,
+    index: IndexCacheStore = None,
+) -> None:
+    # Non-atomic: the Databricks Files API has no native rename, so this is
+    # implemented as copy + delete and can leave partial state on failure.
+    src = ensure_path_spec(src)
+    dst = ensure_path_spec(dst)
+    src_stat = await stat(accessor, src, index)
+    remote_src = backend_path(accessor.config, src)
+    remote_dst = backend_path(accessor.config, dst)
+    if remote_src == remote_dst:
+        # rename(2) onto the same path is a no-op; copy + unlink here would
+        # upload the file onto itself then delete it, destroying the data.
+        # Guard runs after stat so a missing source still raises.
+        return
+    if src_stat.type == FileType.DIRECTORY:
+        if remote_dst.startswith(remote_src + "/"):
+            # Moving a directory into its own subtree would run away in the
+            # recursive copy and then rm_recursive would delete the original.
+            # Refuse before either side effect.
+            raise ValueError(
+                f"cannot move '{src.virtual}' to a subdirectory of "
+                f"itself, '{dst.virtual}'")
+        await copy(accessor, src, dst, index, recursive=True)
+        await rm_recursive(accessor, src, index)
+    else:
+        await copy(accessor, src, dst, index)
+        await unlink(accessor, src, index)
+    await invalidate_after_write(dst)
+    await invalidate_after_unlink(src)

python/mirage/core/databricks_volume/rm.py

@@ -0,0 +1,93 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import ensure_path_spec
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path, virtual_path
+from mirage.core.databricks_volume.stat import stat
+from mirage.core.databricks_volume.unlink import unlink
+from mirage.types import FileType, PathSpec
+from mirage.utils.errors import enoent
+
+
+def _list_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> list:
+    return list(accessor.files.list_directory_contents(remote_path))
+
+
+def _delete_file_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.delete(remote_path)
+
+
+def _delete_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.delete_directory(remote_path)
+
+
+def _remove_tree_recurse(
+    accessor: DatabricksVolumeAccessor,
+    remote_dir: str,
+    removed: list[str],
+) -> None:
+    for entry in _list_directory_sync(accessor, remote_dir):
+        if getattr(entry, "is_directory", False):
+            _remove_tree_recurse(accessor, entry.path, removed)
+        else:
+            _delete_file_sync(accessor, entry.path)
+            removed.append(entry.path)
+    _delete_directory_sync(accessor, remote_dir)
+    removed.append(remote_dir)
+
+
+def _remove_tree_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_root: str,
+) -> list[str]:
+    removed: list[str] = []
+    _remove_tree_recurse(accessor, remote_root, removed)
+    return removed
+
+
+async def rm_recursive(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> list[str]:
+    path = ensure_path_spec(path)
+    file_stat = await stat(accessor, path, index)
+    if file_stat.type != FileType.DIRECTORY:
+        await unlink(accessor, path, index)
+        return [path.mount_path]
+    remote_root = backend_path(accessor.config, path)
+    try:
+        removed = await asyncio.to_thread(_remove_tree_sync, accessor,
+                                          remote_root)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    await invalidate_after_unlink(path)
+    return [virtual_path(accessor.config, backend, "") for backend in removed]

python/mirage/core/databricks_volume/rmdir.py

@@ -0,0 +1,67 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import ensure_path_spec
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.stat import stat
+from mirage.types import FileType, PathSpec
+from mirage.utils.errors import enoent, enotdir
+
+
+def _list_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> list:
+    return list(accessor.files.list_directory_contents(remote_path))
+
+
+def _delete_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.delete_directory(remote_path)
+
+
+async def rmdir(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> None:
+    path = ensure_path_spec(path)
+    file_stat = await stat(accessor, path, index)
+    if file_stat.type != FileType.DIRECTORY:
+        raise enotdir(path)
+    remote_path = backend_path(accessor.config, path)
+    try:
+        entries = await asyncio.to_thread(_list_directory_sync, accessor,
+                                          remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    if entries:
+        raise OSError(f"directory not empty: {path.virtual}")
+    try:
+        await asyncio.to_thread(_delete_directory_sync, accessor, remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    await invalidate_after_unlink(path)

python/mirage/core/databricks_volume/stat.py

@@ -0,0 +1,123 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.types import FileStat, FileType, PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.filetype import guess_type
+from mirage.utils.key_prefix import mount_prefix_of
+
+
+def modified_to_iso(value) -> str | None:
+    if value is None or value == "":
+        return None
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc).isoformat()
+    if isinstance(value, (int, float)):
+        timestamp = value / 1000 if value > 10_000_000_000 else value
+        return datetime.fromtimestamp(timestamp, timezone.utc).isoformat()
+    try:
+        parsed = parsedate_to_datetime(str(value))
+    except (TypeError, ValueError):
+        return str(value)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc).isoformat()
+
+
+def _is_directory(metadata) -> bool:
+    value = getattr(metadata, "is_directory", None)
+    if value is not None:
+        return bool(value)
+    object_type = getattr(metadata, "object_type", None)
+    if object_type is None:
+        return False
+    return str(object_type).lower().endswith("directory")
+
+
+def _name_from_backend_path(path: str) -> str:
+    return path.rstrip("/").rsplit("/", 1)[-1]
+
+
+async def _directory_stat_or_raise(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+    path: PathSpec,
+) -> FileStat:
+    try:
+        await asyncio.to_thread(accessor.files.get_directory_metadata,
+                                remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    return FileStat(name=_name_from_backend_path(remote_path),
+                    type=FileType.DIRECTORY)
+
+
+async def stat(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore | None = None,
+) -> FileStat:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    stripped = path.mount_path.strip("/")
+    if not stripped:
+        return FileStat(name="/", type=FileType.DIRECTORY)
+    if index is not None:
+        prefix = mount_prefix_of(path.virtual, path.resource_path)
+        virtual_key = (prefix.rstrip("/") + "/" + stripped if prefix else "/" +
+                       stripped)
+        lookup = await index.get(virtual_key)
+        if lookup.entry is not None:
+            entry = lookup.entry
+            if entry.resource_type == "folder":
+                return FileStat(name=entry.name, type=FileType.DIRECTORY)
+            return FileStat(name=entry.name,
+                            size=entry.size,
+                            modified=entry.remote_time or None,
+                            type=guess_type(entry.name))
+        parent = virtual_key.rsplit("/", 1)[0] or "/"
+        parent_listing = await index.list_dir(parent)
+        if parent_listing.entries is not None:
+            raise enoent(path)
+    remote_path = backend_path(accessor.config, path)
+    try:
+        metadata = await asyncio.to_thread(accessor.files.get_metadata,
+                                           remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            return await _directory_stat_or_raise(accessor, remote_path, path)
+        raise
+    name = _name_from_backend_path(remote_path)
+    if _is_directory(metadata):
+        return FileStat(name=name, type=FileType.DIRECTORY)
+    size = getattr(metadata, "content_length", None)
+    modified = modified_to_iso(getattr(metadata, "last_modified", None))
+    return FileStat(name=name,
+                    size=size,
+                    modified=modified,
+                    type=guess_type(name))

python/mirage/core/databricks_volume/stream.py

@@ -0,0 +1,89 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+from collections.abc import AsyncIterator
+from typing import BinaryIO
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.read import read_bytes
+from mirage.observe.context import record_stream
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+def _download_contents(response) -> BinaryIO:
+    if isinstance(response, dict):
+        contents = response.get("contents")
+    else:
+        contents = getattr(response, "contents", None)
+    if contents is None:
+        raise RuntimeError("Databricks download response has no contents")
+    return contents
+
+
+def _open_download_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> BinaryIO:
+    return _download_contents(accessor.files.download(remote_path))
+
+
+async def read_stream(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+    chunk_size: int = 8192,
+) -> AsyncIterator[bytes]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+    rec = record_stream("read", path.virtual, "databricks_volume")
+    remote_path = backend_path(accessor.config, path)
+    contents = None
+    try:
+        contents = await asyncio.to_thread(
+            _open_download_sync,
+            accessor,
+            remote_path,
+        )
+        while True:
+            chunk = await asyncio.to_thread(contents.read, chunk_size)
+            if not chunk:
+                return
+            if rec is not None:
+                rec.bytes += len(chunk)
+            yield chunk
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    finally:
+        if contents is not None:
+            await asyncio.to_thread(contents.close)
+
+
+async def range_read(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    start: int,
+    end: int,
+) -> bytes:
+    return await read_bytes(accessor, path, offset=start, size=end - start)

python/mirage/core/databricks_volume/unlink.py

@@ -0,0 +1,55 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import time
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import ensure_path_spec
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.core.databricks_volume.stat import stat
+from mirage.observe.context import record
+from mirage.types import FileType, PathSpec
+from mirage.utils.errors import enoent
+
+
+def _delete_file_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+) -> None:
+    accessor.files.delete(remote_path)
+
+
+async def unlink(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    index: IndexCacheStore = None,
+) -> None:
+    path = ensure_path_spec(path)
+    file_stat = await stat(accessor, path, index)
+    if file_stat.type == FileType.DIRECTORY:
+        raise IsADirectoryError(path.virtual)
+    remote_path = backend_path(accessor.config, path)
+    start_ms = int(time.monotonic() * 1000)
+    try:
+        await asyncio.to_thread(_delete_file_sync, accessor, remote_path)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    record("unlink", path.virtual, "databricks_volume", 0, start_ms)
+    await invalidate_after_unlink(path)

python/mirage/core/databricks_volume/write.py

@@ -0,0 +1,97 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncio
+import time
+from io import BytesIO
+
+from mirage.accessor.databricks_volume import DatabricksVolumeAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.cache.index import IndexCacheStore
+from mirage.core.databricks_volume._helpers import (ensure_path_spec,
+                                                    parent_path)
+from mirage.core.databricks_volume.errors import is_not_found
+from mirage.core.databricks_volume.path import backend_path
+from mirage.observe.context import record
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+def _is_directory_metadata(metadata: object) -> bool:
+    value = getattr(metadata, "is_directory", None)
+    if value is not None:
+        return bool(value)
+    object_type = getattr(metadata, "object_type", None)
+    if object_type is None:
+        return False
+    return str(object_type).lower().endswith("directory")
+
+
+def _ensure_parent_directory_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_parent: str,
+    virtual_target: str,
+) -> None:
+    try:
+        accessor.files.get_directory_metadata(remote_parent)
+        return
+    except Exception as exc:
+        if not is_not_found(exc):
+            raise
+        not_found = exc
+    try:
+        metadata = accessor.files.get_metadata(remote_parent)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise FileNotFoundError(virtual_target) from not_found
+        raise
+    if not _is_directory_metadata(metadata):
+        raise NotADirectoryError(virtual_target)
+
+
+def _upload_bytes_sync(
+    accessor: DatabricksVolumeAccessor,
+    remote_path: str,
+    data: bytes,
+) -> None:
+    accessor.files.upload(remote_path, BytesIO(data), overwrite=True)
+
+
+async def write_bytes(
+    accessor: DatabricksVolumeAccessor,
+    path: PathSpec,
+    data: bytes,
+    index: IndexCacheStore = None,
+) -> None:
+    path = ensure_path_spec(path)
+    parent = parent_path(path)
+    remote_parent = backend_path(accessor.config, parent)
+    remote_path = backend_path(accessor.config, path)
+    start_ms = int(time.monotonic() * 1000)
+    # TODO native async client calling HTTP API as databricks sdk is sync
+    await asyncio.to_thread(
+        _ensure_parent_directory_sync,
+        accessor,
+        remote_parent,
+        path.virtual,
+    )
+    try:
+        await asyncio.to_thread(_upload_bytes_sync, accessor, remote_path,
+                                data)
+    except Exception as exc:
+        if is_not_found(exc):
+            raise enoent(path) from exc
+        raise
+    record("write", path.virtual, "databricks_volume", len(data), start_ms)
+    await invalidate_after_write(path)