msdev 0.9.0__py3-none-any.whl

msdev/core/workspace/access.py

@@ -0,0 +1,1216 @@
+"""Daemon-side, descriptor-relative workspace filesystem operations."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import errno
+import fnmatch
+import functools
+import hashlib
+import json
+import os
+import re
+import secrets
+import selectors
+import shutil
+import stat
+import subprocess
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Generator, Iterable, Iterator
+
+from .paths import normalize_relative
+
+
+MAX_READ_BYTES = 16 * 1024 * 1024
+MAX_STAT_HASH_BYTES = 64 * 1024 * 1024
+MAX_RESULTS = 10_000
+MAX_LIST_RESULTS = 10_000
+MAX_TRAVERSAL_ENTRIES = 100_000
+MAX_SEARCH_SECONDS = 10.0
+MAX_SEARCH_FILES = 10_000
+MAX_SEARCH_BYTES = 256 * 1024 * 1024
+MAX_SEARCH_LINE_BYTES = 1024 * 1024
+_READ_CHUNK_SIZE = 64 * 1024
+_RG_JSON_LINE_BYTES = (2 * MAX_SEARCH_LINE_BYTES) + 64 * 1024
+_REGEX_METACHARACTERS = frozenset(r".^$*+?{}[]\|()")
+
+_O_CLOEXEC = getattr(os, "O_CLOEXEC", 0)
+_O_DIRECTORY = getattr(os, "O_DIRECTORY", 0)
+_O_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+_O_NONBLOCK = getattr(os, "O_NONBLOCK", 0)
+
+
+def workspace_root(root: str | os.PathLike[str] | None) -> Path:
+    """Resolve and validate the root supplied at the RPC boundary."""
+    if not isinstance(root, (str, os.PathLike)):
+        raise ValueError("workspace root must be a path")
+    raw = os.fspath(root)
+    if "\0" in raw:
+        raise ValueError("workspace root must not contain NUL")
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        raise ValueError("workspace root must be absolute")
+    resolved = candidate.resolve(strict=True)
+    if not resolved.is_dir():
+        raise NotADirectoryError(f"workspace root is not a directory: {resolved}")
+    return resolved
+
+
+def _assert_contained(root: Path, candidate: Path) -> Path:
+    try:
+        canonical = candidate.resolve(strict=False)
+        canonical.relative_to(root)
+    except (OSError, RuntimeError, ValueError) as exc:
+        raise PermissionError(
+            f"workspace path escapes workspace root: {candidate}"
+        ) from exc
+    return canonical
+
+
+def resolve_path(
+    root: str | os.PathLike[str] | None,
+    relative: str | None,
+) -> tuple[str, Path]:
+    """Resolve a path for compatibility callers.
+
+    Filesystem operations below do not rely on this check-then-use result; they
+    traverse from an opened root directory descriptor with ``O_NOFOLLOW``.
+    """
+    root_path = workspace_root(root)
+    normalized = normalize_relative("." if relative is None else relative)
+    candidate = (
+        root_path
+        if normalized == "."
+        else root_path.joinpath(*normalized.split("/"))
+    )
+    return normalized, _assert_contained(root_path, candidate)
+
+
+def _require_secure_open_flags() -> None:
+    if not _O_NOFOLLOW or not _O_DIRECTORY:
+        raise RuntimeError(
+            "secure workspace access requires O_NOFOLLOW and O_DIRECTORY"
+        )
+
+
+def _secure_open_error(exc: OSError, relative: str) -> None:
+    if exc.errno in {errno.ELOOP, errno.ENOTDIR}:
+        raise PermissionError(
+            f"workspace path contains a symlink or non-directory ancestor: "
+            f"{relative}"
+        ) from exc
+    raise exc
+
+
+def _open_workspace(
+    root: str | os.PathLike[str] | None,
+) -> tuple[Path, int]:
+    _require_secure_open_flags()
+    root_path = workspace_root(root)
+    flags = os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_CLOEXEC
+    try:
+        descriptor = os.open(root_path.anchor, flags)
+    except OSError as exc:
+        _secure_open_error(exc, ".")
+        raise AssertionError("unreachable")
+    try:
+        for component in root_path.parts[1:]:
+            try:
+                child = os.open(component, flags, dir_fd=descriptor)
+            except OSError as exc:
+                _secure_open_error(exc, str(root_path))
+                raise AssertionError("unreachable")
+            os.close(descriptor)
+            descriptor = child
+    except Exception:
+        os.close(descriptor)
+        raise
+    if not stat.S_ISDIR(os.fstat(descriptor).st_mode):
+        os.close(descriptor)
+        raise NotADirectoryError(f"workspace root is not a directory: {root_path}")
+    return root_path, descriptor
+
+
+def _components(relative: str) -> list[str]:
+    return [] if relative == "." else relative.split("/")
+
+
+def _open_directory_components(
+    root_fd: int,
+    components: Iterable[str],
+    relative: str,
+) -> int:
+    descriptor = os.dup(root_fd)
+    try:
+        for component in components:
+            try:
+                child = os.open(
+                    component,
+                    os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_CLOEXEC,
+                    dir_fd=descriptor,
+                )
+            except OSError as exc:
+                _secure_open_error(exc, relative)
+                raise AssertionError("unreachable")
+            os.close(descriptor)
+            descriptor = child
+        return descriptor
+    except Exception:
+        os.close(descriptor)
+        raise
+
+
+def _open_parent(root_fd: int, relative: str) -> tuple[int, str]:
+    parts = _components(relative)
+    if not parts:
+        raise IsADirectoryError("workspace root cannot be used as a file")
+    return (
+        _open_directory_components(root_fd, parts[:-1], relative),
+        parts[-1],
+    )
+
+
+def _open_relative(
+    root_fd: int,
+    relative: str,
+    flags: int,
+    *,
+    mode: int = 0o600,
+) -> int:
+    parts = _components(relative)
+    if not parts:
+        return os.dup(root_fd)
+    parent_fd = _open_directory_components(root_fd, parts[:-1], relative)
+    try:
+        try:
+            return os.open(
+                parts[-1],
+                flags | _O_NOFOLLOW | _O_CLOEXEC,
+                mode,
+                dir_fd=parent_fd,
+            )
+        except OSError as exc:
+            _secure_open_error(exc, relative)
+            raise AssertionError("unreachable")
+    finally:
+        os.close(parent_fd)
+
+
+def _join_relative(parent: str, name: str) -> str:
+    return name if parent == "." else f"{parent}/{name}"
+
+
+def _path_type(metadata: os.stat_result) -> str:
+    mode = metadata.st_mode
+    if stat.S_ISLNK(mode):
+        return "symlink"
+    if stat.S_ISREG(mode):
+        return "file"
+    if stat.S_ISDIR(mode):
+        return "directory"
+    return "other"
+
+
+def _metadata(
+    relative: str,
+    metadata: os.stat_result,
+    *,
+    sha256: str | None = None,
+) -> dict[str, Any]:
+    kind = _path_type(metadata)
+    value: dict[str, Any] = {
+        "path": relative,
+        "type": kind,
+        "size": metadata.st_size if kind != "directory" else None,
+        "mtime_ns": metadata.st_mtime_ns,
+    }
+    if sha256 is not None:
+        value["sha256"] = sha256
+    return value
+
+
+def _sha256_fd(descriptor: int, max_bytes: int | None = None) -> str | None:
+    digest = hashlib.sha256()
+    total = 0
+    while True:
+        read_size = 1024 * 1024
+        if max_bytes is not None:
+            read_size = min(read_size, max_bytes - total + 1)
+        chunk = os.read(descriptor, read_size)
+        if not chunk:
+            return digest.hexdigest()
+        total += len(chunk)
+        if max_bytes is not None and total > max_bytes:
+            return None
+        digest.update(chunk)
+
+
+def stat_path(
+    root: str | os.PathLike[str] | None,
+    relative: str | None = ".",
+) -> dict[str, Any]:
+    normalized = normalize_relative("." if relative is None else relative)
+    _, root_fd = _open_workspace(root)
+    try:
+        if normalized == ".":
+            return _metadata(".", os.fstat(root_fd))
+        parent_fd, leaf = _open_parent(root_fd, normalized)
+        try:
+            metadata = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+            kind = _path_type(metadata)
+            if kind == "file":
+                descriptor = os.open(
+                    leaf,
+                    os.O_RDONLY | _O_NONBLOCK | _O_NOFOLLOW | _O_CLOEXEC,
+                    dir_fd=parent_fd,
+                )
+                try:
+                    metadata = os.fstat(descriptor)
+                    if metadata.st_size > MAX_STAT_HASH_BYTES:
+                        value = _metadata(normalized, metadata)
+                        value.update(
+                            {
+                                "sha256": None,
+                                "sha256_truncated": True,
+                                "sha256_reason": (
+                                    "file exceeds stat hash limit of "
+                                    f"{MAX_STAT_HASH_BYTES} bytes"
+                                ),
+                            }
+                        )
+                        return value
+                    digest = _sha256_fd(descriptor, MAX_STAT_HASH_BYTES)
+                    if digest is None:
+                        value = _metadata(normalized, metadata)
+                        value.update(
+                            {
+                                "sha256": None,
+                                "sha256_truncated": True,
+                                "sha256_reason": (
+                                    "file exceeded stat hash limit of "
+                                    f"{MAX_STAT_HASH_BYTES} bytes while reading"
+                                ),
+                            }
+                        )
+                        return value
+                    return _metadata(normalized, metadata, sha256=digest)
+                finally:
+                    os.close(descriptor)
+            if kind == "directory":
+                descriptor = os.open(
+                    leaf,
+                    os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_CLOEXEC,
+                    dir_fd=parent_fd,
+                )
+                try:
+                    metadata = os.fstat(descriptor)
+                finally:
+                    os.close(descriptor)
+            return _metadata(normalized, metadata)
+        finally:
+            os.close(parent_fd)
+    except OSError as exc:
+        _secure_open_error(exc, normalized)
+        raise AssertionError("unreachable")
+    finally:
+        os.close(root_fd)
+
+
+def _positive_limit(value: Any, name: str, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ValueError(f"{name} must be an integer")
+    if not 1 <= value <= maximum:
+        raise ValueError(f"{name} must be between 1 and {maximum}")
+    return value
+
+
+def read_file(
+    root: str | os.PathLike[str] | None,
+    relative: str | None,
+    max_bytes: int = 1024 * 1024,
+) -> dict[str, Any]:
+    limit = _positive_limit(max_bytes, "max_bytes", MAX_READ_BYTES)
+    normalized = normalize_relative("." if relative is None else relative)
+    _, root_fd = _open_workspace(root)
+    descriptor = None
+    try:
+        descriptor = _open_relative(
+            root_fd,
+            normalized,
+            os.O_RDONLY | _O_NONBLOCK,
+        )
+        metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(metadata.st_mode):
+            if stat.S_ISDIR(metadata.st_mode):
+                raise IsADirectoryError(
+                    f"workspace path is a directory: {normalized}"
+                )
+            raise ValueError(
+                f"workspace path is not a regular file: {normalized}"
+            )
+        content = bytearray()
+        while len(content) <= limit:
+            chunk = os.read(
+                descriptor,
+                min(_READ_CHUNK_SIZE, limit + 1 - len(content)),
+            )
+            if not chunk:
+                break
+            content.extend(chunk)
+        if len(content) > limit:
+            raise ValueError(
+                f"refusing to read {normalized!r}: file size is exceeding "
+                f"read limit of {limit} bytes"
+            )
+        payload = bytes(content)
+        return {
+            "path": normalized,
+            "size": len(payload),
+            "sha256": hashlib.sha256(payload).hexdigest(),
+            "content_base64": base64.b64encode(payload).decode("ascii"),
+        }
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+        os.close(root_fd)
+
+
+def _iter_sorted_names_fd(
+    directory_fd: int,
+    *,
+    budget: "_TraversalBudget | None" = None,
+) -> Iterator[str]:
+    """Yield a sorted, bounded snapshot of directory names."""
+    scan = budget or _TraversalBudget(MAX_TRAVERSAL_ENTRIES)
+    names: list[str] = []
+    os.lseek(directory_fd, 0, os.SEEK_SET)
+    with os.scandir(directory_fd) as entries:
+        for entry in entries:
+            if scan.deadline is not None and time.monotonic() >= scan.deadline:
+                scan.truncated = True
+                scan.deadline_exceeded = True
+                break
+            if scan.visited >= scan.maximum:
+                scan.truncated = True
+                break
+            scan.visited += 1
+            names.append(entry.name)
+    names.sort()
+    yield from names
+
+
+def list_directory(
+    root: str | os.PathLike[str] | None,
+    relative: str | None = ".",
+) -> dict[str, Any]:
+    normalized = normalize_relative("." if relative is None else relative)
+    _, root_fd = _open_workspace(root)
+    directory_fd = None
+    try:
+        directory_fd = _open_relative(
+            root_fd,
+            normalized,
+            os.O_RDONLY | _O_DIRECTORY,
+        )
+        entries: list[dict[str, Any]] = []
+        truncated = False
+        budget = _TraversalBudget(MAX_TRAVERSAL_ENTRIES)
+        for name in _iter_sorted_names_fd(directory_fd, budget=budget):
+            try:
+                metadata = os.stat(
+                    name,
+                    dir_fd=directory_fd,
+                    follow_symlinks=False,
+                )
+            except FileNotFoundError:
+                continue
+            if len(entries) == MAX_LIST_RESULTS:
+                truncated = True
+                break
+            entries.append(
+                _metadata(_join_relative(normalized, name), metadata)
+            )
+        return {
+            "path": normalized,
+            "entries": entries,
+            "truncated": truncated or budget.truncated,
+            "visited_entries": budget.visited,
+        }
+    finally:
+        if directory_fd is not None:
+            os.close(directory_fd)
+        os.close(root_fd)
+
+
+def _max_results(value: Any) -> int:
+    return _positive_limit(value, "max_results", MAX_RESULTS)
+
+
+@dataclass
+class _TraversalBudget:
+    maximum: int = MAX_TRAVERSAL_ENTRIES
+    visited: int = 0
+    truncated: bool = False
+    deadline: float | None = None
+    deadline_exceeded: bool = False
+
+def _walk_tree_fd(
+    directory_fd: int,
+    relative: str = ".",
+    budget: _TraversalBudget | None = None,
+) -> Generator[tuple[str, os.stat_result, int, str], None, None]:
+    budget = budget or _TraversalBudget()
+    for name in _iter_sorted_names_fd(directory_fd, budget=budget):
+        try:
+            metadata = os.stat(
+                name,
+                dir_fd=directory_fd,
+                follow_symlinks=False,
+            )
+        except FileNotFoundError:
+            continue
+        child_relative = _join_relative(relative, name)
+        yield child_relative, metadata, directory_fd, name
+        if not stat.S_ISDIR(metadata.st_mode):
+            continue
+        try:
+            child_fd = os.open(
+                name,
+                os.O_RDONLY | _O_DIRECTORY | _O_NOFOLLOW | _O_CLOEXEC,
+                dir_fd=directory_fd,
+            )
+        except (FileNotFoundError, NotADirectoryError):
+            continue
+        except OSError as exc:
+            if exc.errno == errno.ELOOP:
+                continue
+            raise
+        try:
+            yield from _walk_tree_fd(child_fd, child_relative, budget)
+        finally:
+            os.close(child_fd)
+        if budget.truncated:
+            return
+
+
+def _glob_match(relative: str, pattern: str) -> bool:
+    path_parts = () if relative == "." else tuple(relative.split("/"))
+    pattern_parts = () if pattern == "." else tuple(pattern.split("/"))
+
+    @functools.lru_cache(maxsize=None)
+    def match(path_index: int, pattern_index: int) -> bool:
+        if pattern_index == len(pattern_parts):
+            return path_index == len(path_parts)
+        current = pattern_parts[pattern_index]
+        if current == "**":
+            return match(path_index, pattern_index + 1) or (
+                path_index < len(path_parts)
+                and match(path_index + 1, pattern_index)
+            )
+        return (
+            path_index < len(path_parts)
+            and fnmatch.fnmatchcase(path_parts[path_index], current)
+            and match(path_index + 1, pattern_index + 1)
+        )
+
+    return match(0, 0)
+
+
+def glob_paths(
+    root: str | os.PathLike[str] | None,
+    pattern: str,
+    max_results: int = 1000,
+) -> dict[str, Any]:
+    limit = _max_results(max_results)
+    normalized_pattern = normalize_relative(pattern)
+    _, root_fd = _open_workspace(root)
+    matches: list[dict[str, Any]] = []
+    truncated = False
+    budget = _TraversalBudget(MAX_TRAVERSAL_ENTRIES)
+    walker = _walk_tree_fd(root_fd, budget=budget)
+    try:
+        if normalized_pattern == ".":
+            matches.append(_metadata(".", os.fstat(root_fd)))
+        else:
+            for relative, metadata, _parent_fd, _name in walker:
+                if not _glob_match(relative, normalized_pattern):
+                    continue
+                if len(matches) == limit:
+                    truncated = True
+                    break
+                matches.append(_metadata(relative, metadata))
+    finally:
+        walker.close()
+        os.close(root_fd)
+    return {
+        "pattern": normalized_pattern,
+        "matches": matches,
+        "truncated": truncated or budget.truncated,
+        "visited_entries": budget.visited,
+    }
+
+
+def _strict_base64(value: Any) -> bytes:
+    if not isinstance(value, str):
+        raise ValueError("content_base64 must be a base64 string")
+    try:
+        decoded = base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("content_base64 is not valid base64") from exc
+    if base64.b64encode(decoded).decode("ascii") != value:
+        raise ValueError("content_base64 is not canonical base64")
+    return decoded
+
+
+def _expected_digest(value: Any) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not re.fullmatch(r"[0-9a-fA-F]{64}", value):
+        raise ValueError(
+            "expected_sha256 must be a 64-character hexadecimal digest"
+        )
+    return value.lower()
+
+
+@dataclass
+class _PathLockEntry:
+    lock: threading.Lock
+    users: int = 0
+
+
+_PATH_LOCK_GUARD = threading.Lock()
+_PATH_LOCKS: dict[tuple[str, str], _PathLockEntry] = {}
+
+
+@contextmanager
+def _path_lock(key: tuple[str, str]) -> Iterator[None]:
+    with _PATH_LOCK_GUARD:
+        entry = _PATH_LOCKS.get(key)
+        if entry is None:
+            entry = _PathLockEntry(threading.Lock())
+            _PATH_LOCKS[key] = entry
+        entry.users += 1
+    entry.lock.acquire()
+    try:
+        yield
+    finally:
+        entry.lock.release()
+        with _PATH_LOCK_GUARD:
+            entry.users -= 1
+            if entry.users == 0 and _PATH_LOCKS.get(key) is entry:
+                del _PATH_LOCKS[key]
+
+
+def _existing_digest_and_mode(
+    parent_fd: int,
+    leaf: str,
+) -> tuple[str | None, int | None]:
+    try:
+        descriptor = os.open(
+            leaf,
+            os.O_RDONLY | _O_NONBLOCK | _O_NOFOLLOW | _O_CLOEXEC,
+            dir_fd=parent_fd,
+        )
+    except FileNotFoundError:
+        return None, None
+    except OSError as exc:
+        if exc.errno == errno.ELOOP:
+            return None, None
+        raise
+    try:
+        metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(metadata.st_mode):
+            return None, None
+        return _sha256_fd(descriptor), stat.S_IMODE(metadata.st_mode)
+    finally:
+        os.close(descriptor)
+
+
+def _create_temporary_file(parent_fd: int) -> tuple[int, str]:
+    for _ in range(100):
+        name = f".msdev-write-{secrets.token_hex(12)}"
+        try:
+            descriptor = os.open(
+                name,
+                os.O_WRONLY
+                | os.O_CREAT
+                | os.O_EXCL
+                | _O_NOFOLLOW
+                | _O_CLOEXEC,
+                0o600,
+                dir_fd=parent_fd,
+            )
+            return descriptor, name
+        except FileExistsError:
+            continue
+    raise FileExistsError("could not allocate a unique workspace temp file")
+
+
+def _write_all(descriptor: int, content: bytes) -> None:
+    view = memoryview(content)
+    while view:
+        written = os.write(descriptor, view)
+        if written <= 0:
+            raise OSError("short write to workspace temporary file")
+        view = view[written:]
+
+
+def atomic_write(
+    root: str | os.PathLike[str] | None,
+    relative: str | None,
+    content_base64: str,
+    expected_sha256: str | None = None,
+) -> dict[str, Any]:
+    root_path = workspace_root(root)
+    normalized = normalize_relative("." if relative is None else relative)
+    key = (str(root_path), normalized)
+    with _path_lock(key):
+        content = _strict_base64(content_base64)
+        expected = _expected_digest(expected_sha256)
+        _, root_fd = _open_workspace(root_path)
+        parent_fd = None
+        temporary_name = None
+        temporary_fd = None
+        try:
+            parent_fd, leaf = _open_parent(root_fd, normalized)
+            try:
+                existing = os.stat(
+                    leaf,
+                    dir_fd=parent_fd,
+                    follow_symlinks=False,
+                )
+            except FileNotFoundError:
+                existing = None
+            if existing is not None and stat.S_ISDIR(existing.st_mode):
+                raise IsADirectoryError(
+                    f"workspace path is a directory: {normalized}"
+                )
+            if (
+                existing is not None
+                and not stat.S_ISREG(existing.st_mode)
+                and not stat.S_ISLNK(existing.st_mode)
+            ):
+                raise ValueError(
+                    f"workspace path is not a regular file: {normalized}"
+                )
+
+            current, existing_mode = _existing_digest_and_mode(parent_fd, leaf)
+            if expected is not None and current != expected:
+                raise RuntimeError(
+                    f"workspace file changed before write: {normalized} "
+                    f"(expected {expected}, found {current or 'missing'})"
+                )
+
+            temporary_fd, temporary_name = _create_temporary_file(parent_fd)
+            if existing_mode is not None:
+                os.fchmod(temporary_fd, existing_mode)
+            _write_all(temporary_fd, content)
+            os.fsync(temporary_fd)
+            os.close(temporary_fd)
+            temporary_fd = None
+
+            if expected is not None:
+                latest, _ = _existing_digest_and_mode(parent_fd, leaf)
+                if latest != expected:
+                    raise RuntimeError(
+                        f"workspace file changed before replace: {normalized} "
+                        f"(expected {expected}, found {latest or 'missing'})"
+                    )
+            os.replace(
+                temporary_name,
+                leaf,
+                src_dir_fd=parent_fd,
+                dst_dir_fd=parent_fd,
+            )
+            temporary_name = None
+            os.fsync(parent_fd)
+        finally:
+            if temporary_fd is not None:
+                os.close(temporary_fd)
+            if temporary_name is not None and parent_fd is not None:
+                try:
+                    os.unlink(temporary_name, dir_fd=parent_fd)
+                except FileNotFoundError:
+                    pass
+            if parent_fd is not None:
+                os.close(parent_fd)
+            os.close(root_fd)
+    return {
+        "path": normalized,
+        "size": len(content),
+        "sha256": hashlib.sha256(content).hexdigest(),
+        "atomic": True,
+    }
+
+
+def delete_file(
+    root: str | os.PathLike[str] | None,
+    relative: str | None,
+) -> dict[str, Any]:
+    root_path = workspace_root(root)
+    normalized = normalize_relative("." if relative is None else relative)
+    key = (str(root_path), normalized)
+    with _path_lock(key):
+        _, root_fd = _open_workspace(root_path)
+        parent_fd = None
+        try:
+            parent_fd, leaf = _open_parent(root_fd, normalized)
+            try:
+                metadata = os.stat(
+                    leaf,
+                    dir_fd=parent_fd,
+                    follow_symlinks=False,
+                )
+            except FileNotFoundError as exc:
+                raise FileNotFoundError(
+                    f"workspace file does not exist: {normalized}"
+                ) from exc
+            if stat.S_ISDIR(metadata.st_mode):
+                raise IsADirectoryError(
+                    "workspace delete only supports files, not directories: "
+                    f"{normalized}"
+                )
+            if not (
+                stat.S_ISREG(metadata.st_mode)
+                or stat.S_ISLNK(metadata.st_mode)
+            ):
+                raise ValueError(
+                    f"workspace path is not a regular file: {normalized}"
+                )
+            os.unlink(leaf, dir_fd=parent_fd)
+        finally:
+            if parent_fd is not None:
+                os.close(parent_fd)
+            os.close(root_fd)
+    return {"path": normalized, "deleted": True}
+
+
+def _search_scopes(paths: Any) -> list[str]:
+    raw_paths = ["."] if paths is None else paths
+    if (
+        not isinstance(raw_paths, list)
+        or not raw_paths
+        or not all(isinstance(item, str) for item in raw_paths)
+    ):
+        raise ValueError("search paths must be a non-empty string array")
+    return sorted({normalize_relative(item) for item in raw_paths})
+
+
+@dataclass
+class _SearchBudget:
+    started: float
+    deadline: float
+    files_visited: int = 0
+    bytes_read: int = 0
+    reasons: set[str] | None = None
+
+    @classmethod
+    def create(cls) -> "_SearchBudget":
+        started = time.monotonic()
+        return cls(started, started + MAX_SEARCH_SECONDS, reasons=set())
+
+    def mark(self, reason: str) -> None:
+        assert self.reasons is not None
+        self.reasons.add(reason)
+
+    def has_reason(self, reason: str) -> bool:
+        assert self.reasons is not None
+        return reason in self.reasons
+
+    def remaining_seconds(self) -> float:
+        return self.deadline - time.monotonic()
+
+    def check_deadline(self) -> bool:
+        if self.remaining_seconds() <= 0:
+            self.mark("deadline")
+            return False
+        return True
+
+    def claim_file(self, size: int) -> bool:
+        if not self.check_deadline():
+            return False
+        if self.files_visited >= MAX_SEARCH_FILES:
+            self.mark("files")
+            return False
+        if size > MAX_SEARCH_BYTES - self.bytes_read:
+            self.mark("bytes")
+            return False
+        self.files_visited += 1
+        self.bytes_read += size
+        return True
+
+
+def _iter_search_files(
+    root_fd: int,
+    scopes: Iterable[str],
+    traversal: _TraversalBudget,
+) -> Generator[tuple[str, int], None, None]:
+    for scope in scopes:
+        try:
+            scope_fd = _open_relative(
+                root_fd,
+                scope,
+                os.O_RDONLY | _O_NONBLOCK,
+            )
+        except FileNotFoundError as exc:
+            raise FileNotFoundError(f"search path does not exist: {scope}") from exc
+        metadata = os.fstat(scope_fd)
+        if stat.S_ISREG(metadata.st_mode):
+            try:
+                yield scope, scope_fd
+            finally:
+                os.close(scope_fd)
+            continue
+        if not stat.S_ISDIR(metadata.st_mode):
+            os.close(scope_fd)
+            continue
+        try:
+            walker = _walk_tree_fd(scope_fd, scope, traversal)
+            try:
+                for relative, child_metadata, parent_fd, name in walker:
+                    if not stat.S_ISREG(child_metadata.st_mode):
+                        continue
+                    try:
+                        file_fd = os.open(
+                            name,
+                            os.O_RDONLY
+                            | _O_NONBLOCK
+                            | _O_NOFOLLOW
+                            | _O_CLOEXEC,
+                            dir_fd=parent_fd,
+                        )
+                    except (FileNotFoundError, PermissionError):
+                        continue
+                    except OSError as exc:
+                        if exc.errno == errno.ELOOP:
+                            continue
+                        raise
+                    try:
+                        if stat.S_ISREG(os.fstat(file_fd).st_mode):
+                            yield relative, file_fd
+                    finally:
+                        os.close(file_fd)
+            finally:
+                walker.close()
+        finally:
+            os.close(scope_fd)
+
+
+def _search_glob_match(relative: str, pattern: str | None) -> bool:
+    if pattern is None:
+        return True
+    if "/" not in pattern:
+        return fnmatch.fnmatchcase(relative.rsplit("/", 1)[-1], pattern)
+    return _glob_match(relative, pattern)
+
+
+def _python_file_matches(
+    descriptor: int,
+    relative: str,
+    literal: str,
+    budget: _SearchBudget,
+) -> Iterator[dict[str, Any]]:
+    with os.fdopen(
+        os.dup(descriptor),
+        "rb",
+    ) as handle:
+        line_number = 0
+        while budget.check_deadline():
+            line = handle.readline(MAX_SEARCH_LINE_BYTES + 1)
+            if not line:
+                return
+            line_number += 1
+            oversized = len(line) > MAX_SEARCH_LINE_BYTES
+            while oversized and not line.endswith(b"\n"):
+                if not budget.check_deadline():
+                    return
+                fragment = handle.readline(MAX_SEARCH_LINE_BYTES + 1)
+                if not fragment or fragment.endswith(b"\n"):
+                    break
+            if oversized:
+                budget.mark("line_size")
+                continue
+            text = line.decode("utf-8", errors="replace")
+            if literal in text:
+                yield {
+                    "path": relative,
+                    "line": line_number,
+                    "text": text.rstrip("\r\n"),
+                }
+
+
+def _rg_match_message(line: bytes, relative: str) -> dict[str, Any] | None:
+    try:
+        message = json.loads(line)
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    if message.get("type") != "match":
+        return None
+    data = message.get("data") or {}
+    line_number = data.get("line_number")
+    text = (data.get("lines") or {}).get("text")
+    if not isinstance(line_number, int) or not isinstance(text, str):
+        return None
+    return {
+        "path": relative,
+        "line": line_number,
+        "text": text.rstrip("\r\n"),
+    }
+
+
+def _rg_file_matches(
+    executable: str,
+    descriptor: int,
+    relative: str,
+    pattern: str,
+    max_matches: int,
+    budget: _SearchBudget,
+) -> Generator[dict[str, Any], None, None]:
+    os.lseek(descriptor, 0, os.SEEK_SET)
+    process = subprocess.Popen(
+        [
+            executable,
+            "--json",
+            "--line-number",
+            "--color",
+            "never",
+            "--text",
+            "--no-config",
+            "--max-columns",
+            str(MAX_SEARCH_LINE_BYTES),
+            "--max-filesize",
+            str(MAX_SEARCH_BYTES),
+            "--max-count",
+            str(max_matches),
+            "--",
+            pattern,
+            "-",
+        ],
+        stdin=descriptor,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+    )
+    assert process.stdout is not None
+    buffer = bytearray()
+    discarding_line = False
+    stream_finished = False
+    try:
+        with selectors.DefaultSelector() as selector:
+            selector.register(process.stdout, selectors.EVENT_READ)
+            while not stream_finished:
+                remaining = budget.remaining_seconds()
+                if remaining <= 0:
+                    budget.mark("deadline")
+                    break
+                events = selector.select(min(remaining, 0.1))
+                if not events:
+                    if process.poll() is not None:
+                        break
+                    continue
+                for _key, _mask in events:
+                    chunk = os.read(process.stdout.fileno(), _READ_CHUNK_SIZE)
+                    if not chunk:
+                        stream_finished = True
+                        break
+                    while chunk:
+                        newline = chunk.find(b"\n")
+                        if discarding_line:
+                            if newline < 0:
+                                chunk = b""
+                            else:
+                                discarding_line = False
+                                chunk = chunk[newline + 1 :]
+                            continue
+                        if newline < 0:
+                            if len(buffer) + len(chunk) > _RG_JSON_LINE_BYTES:
+                                buffer.clear()
+                                discarding_line = True
+                                budget.mark("line_size")
+                            else:
+                                buffer.extend(chunk)
+                            chunk = b""
+                            continue
+                        segment = chunk[:newline]
+                        chunk = chunk[newline + 1 :]
+                        if len(buffer) + len(segment) > _RG_JSON_LINE_BYTES:
+                            buffer.clear()
+                            budget.mark("line_size")
+                            continue
+                        buffer.extend(segment)
+                        match = _rg_match_message(bytes(buffer), relative)
+                        buffer.clear()
+                        if match is not None:
+                            yield match
+        if budget.has_reason("deadline"):
+            if process.poll() is None:
+                process.kill()
+            returncode = process.wait()
+        else:
+            try:
+                returncode = process.wait(
+                    timeout=max(0.001, budget.remaining_seconds())
+                )
+            except subprocess.TimeoutExpired:
+                budget.mark("deadline")
+                if process.poll() is None:
+                    process.kill()
+                returncode = process.wait()
+        if returncode not in {0, 1} and not budget.has_reason("deadline"):
+            raise ValueError(f"rg search failed with exit code {returncode}")
+    finally:
+        if process.poll() is None:
+            process.kill()
+        process.wait()
+        process.stdout.close()
+
+
+def _search_python(
+    root_fd: int,
+    pattern: str,
+    scopes: list[str],
+    glob_filter: str | None,
+    limit: int,
+) -> dict[str, Any]:
+    if any(character in _REGEX_METACHARACTERS for character in pattern):
+        raise ValueError(
+            "Python fallback search only supports literal substring patterns; "
+            "ripgrep is required for regular-expression metacharacters"
+        )
+    matches: list[dict[str, Any]] = []
+    budget = _SearchBudget.create()
+    traversal = _TraversalBudget(
+        MAX_TRAVERSAL_ENTRIES,
+        deadline=budget.deadline,
+    )
+    files = _iter_search_files(root_fd, scopes, traversal)
+    try:
+        for relative, descriptor in files:
+            if not _search_glob_match(relative, glob_filter):
+                continue
+            if not budget.claim_file(os.fstat(descriptor).st_size):
+                break
+            for match in _python_file_matches(
+                descriptor,
+                relative,
+                pattern,
+                budget,
+            ):
+                if len(matches) == limit:
+                    budget.mark("results")
+                    break
+                matches.append(match)
+            if budget.reasons:
+                break
+    finally:
+        files.close()
+    if traversal.deadline_exceeded:
+        budget.mark("deadline")
+    elif traversal.truncated:
+        budget.mark("entries")
+    return {
+        "matches": matches,
+        "truncated": bool(budget.reasons),
+        "engine": "python",
+        "semantics": "literal",
+        "files_visited": budget.files_visited,
+        "bytes_read": budget.bytes_read,
+        "truncation_reasons": sorted(budget.reasons or ()),
+    }
+
+
+def _search_rg(
+    executable: str,
+    root_fd: int,
+    pattern: str,
+    scopes: list[str],
+    glob_filter: str | None,
+    limit: int,
+) -> dict[str, Any]:
+    matches: list[dict[str, Any]] = []
+    budget = _SearchBudget.create()
+    traversal = _TraversalBudget(
+        MAX_TRAVERSAL_ENTRIES,
+        deadline=budget.deadline,
+    )
+    files = _iter_search_files(root_fd, scopes, traversal)
+    try:
+        for relative, descriptor in files:
+            if not _search_glob_match(relative, glob_filter):
+                continue
+            if not budget.claim_file(os.fstat(descriptor).st_size):
+                break
+            file_matches = _rg_file_matches(
+                executable,
+                descriptor,
+                relative,
+                pattern,
+                limit - len(matches) + 1,
+                budget,
+            )
+            try:
+                for match in file_matches:
+                    if len(matches) == limit:
+                        budget.mark("results")
+                        break
+                    matches.append(match)
+            finally:
+                file_matches.close()
+            if budget.reasons:
+                break
+    finally:
+        files.close()
+    if traversal.deadline_exceeded:
+        budget.mark("deadline")
+    elif traversal.truncated:
+        budget.mark("entries")
+    return {
+        "matches": matches,
+        "truncated": bool(budget.reasons),
+        "engine": "rg",
+        "files_visited": budget.files_visited,
+        "bytes_read": budget.bytes_read,
+        "truncation_reasons": sorted(budget.reasons or ()),
+    }
+
+
+def search(
+    root: str | os.PathLike[str] | None,
+    pattern: str,
+    paths: list[str] | None = None,
+    glob: str | None = None,
+    max_results: int = 1000,
+) -> dict[str, Any]:
+    if not isinstance(pattern, str) or "\0" in pattern:
+        raise ValueError("search pattern must be a NUL-free string")
+    limit = _max_results(max_results)
+    scopes = _search_scopes(paths)
+    glob_filter = normalize_relative(glob) if glob is not None else None
+    _, root_fd = _open_workspace(root)
+    try:
+        executable = shutil.which("rg")
+        if executable is not None:
+            try:
+                return _search_rg(
+                    executable,
+                    root_fd,
+                    pattern,
+                    scopes,
+                    glob_filter,
+                    limit,
+                )
+            except OSError:
+                pass
+        return _search_python(
+            root_fd,
+            pattern,
+            scopes,
+            glob_filter,
+            limit,
+        )
+    finally:
+        os.close(root_fd)