superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/core/remote_mode.py

@@ -1,214 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Distributed / LAN deployment mode — the single ``SLM_REMOTE`` switch.
-
-SuperLocalMemory historically assumes every dashboard browser, MCP client,
-and API caller lives on ``127.0.0.1``. That assumption breaks three things
-for users who deploy SLM on a server and reach it across a LAN (issue #39):
-
-  1. ``/internal/token`` refuses any non-loopback client → Brain page can't
-     fetch the install token → "Couldn't load Brain".
-  2. The MCP Streamable-HTTP transport is **stateful** — every call must
-     replay the ``Mcp-Session-Id`` from the ``initialize`` handshake. A
-     gateway/hub that forwards a tool call without replaying it gets
-     ``-32600 Session not found``.
-  3. Dashboard CSRF origin checks only accept loopback origins.
-
-``SLM_REMOTE=1`` flips all three assumptions at once, **default OFF** so the
-loopback-only security posture is unchanged for the 99% local case. LAN
-access is still gated by an explicit IP allowlist (``SLM_MCP_ALLOWED_HOSTS``)
-— remote mode alone does not throw the doors open.
-
-Granular overrides (each implied by ``SLM_REMOTE=1`` but usable alone):
-  * ``SLM_MCP_STATELESS=1`` — stateless MCP transport only (gateway fix),
-    without opening the dashboard token endpoint.
-
-Security note (WORSTCASE): stateless MCP drops per-session isolation, and
-serving the install token to a LAN host lets any allowlisted machine read
-the brain. Keep the allowlist specific (never blanket ``*`` unless the
-network is fully trusted) — see ``docs/distributed-deployment.md``.
-"""
-
-from __future__ import annotations
-
-import ipaddress
-import os
-
-_TRUTHY = frozenset({"1", "true", "yes", "on"})
-
-
-def _is_truthy(value: str | None) -> bool:
-    return bool(value) and value.strip().lower() in _TRUTHY
-
-
-def is_remote_mode() -> bool:
-    """True iff ``SLM_REMOTE`` opts this daemon into LAN/distributed mode."""
-    return _is_truthy(os.environ.get("SLM_REMOTE"))
-
-
-def mcp_stateless() -> bool:
-    """True iff the MCP Streamable-HTTP transport should run fully stateless.
-
-    **Default is True** (mcp 2.0.0 fully-stateless contract). Stateless mode
-    lets any gateway/hub forward ``tools/call`` without replaying the
-    ``Mcp-Session-Id`` handshake (issue #39 Issue 3) and is required for
-    ``Client(mode="auto")`` discover probes to stay connection-safe.
-
-    Opt-out: set ``SLM_MCP_STATEFUL=1`` to force stateful Streamable-HTTP
-    (session IDs; event store still unused unless the caller passes one).
-    ``SLM_REMOTE`` / ``SLM_MCP_STATELESS`` remain recognized as positive
-    signals but are no longer required — the default is already stateless.
-
-    Application-level ``session_init`` / ``close_session`` are orthogonal
-    (session_id is a string parameter persisted in the memories table).
-    """
-    if _is_truthy(os.environ.get("SLM_MCP_STATEFUL")):
-        return False
-    # Explicit SLM_MCP_STATELESS=0/false still honoured as opt-out when set.
-    raw = os.environ.get("SLM_MCP_STATELESS")
-    if raw is not None and raw.strip() != "":
-        return _is_truthy(raw)
-    return True
-
-
-def _allowlist_entries() -> list[str]:
-    """Trusted-client allowlist, from ``SLM_MCP_ALLOWED_HOSTS``.
-
-    Reuses the existing LAN allowlist the user already sets for MCP DNS-rebinding
-    protection so there is ONE place to configure trusted hosts. Entries are
-    comma-separated and may be: ``*`` (any), an exact IP, a CIDR block
-    (``192.168.1.0/24``), or a prefix wildcard (``192.168.*``). A trailing
-    ``:port`` / ``:*`` (host-header style) is ignored for client-IP matching.
-    """
-    raw = os.environ.get("SLM_MCP_ALLOWED_HOSTS", "").strip()
-    return [e.strip() for e in raw.split(",") if e.strip()]
-
-
-def _strip_port(entry: str) -> str:
-    """Drop a trailing ``:port`` / ``:*`` host-header suffix.
-
-    Handles plain ``host[:port]`` and CIDR ``a.b.c.d/n[:port]`` (v3.6.12 lan-1:
-    a CIDR written with a host-header port suffix used to fail ip_network() and
-    silently deny ALL clients). Bracketless IPv6 literals (≥2 colons, no '/')
-    are left untouched.
-    """
-    e = entry.strip()
-    if "/" in e:
-        # CIDR — strip anything after the network prefix (a stray :port/:*)
-        return e.partition(":")[0]
-    if e.count(":") == 1:  # host:port or host:* (IPv4 / hostname)
-        return e.split(":", 1)[0]
-    return e
-
-
-def _host_matches(entry: str, client_host: str, client_ip) -> bool:
-    host = _strip_port(entry).strip()
-    if not host:
-        return False
-    if host == "*":
-        return True
-    if "/" in host and client_ip is not None:
-        try:
-            return client_ip in ipaddress.ip_network(host, strict=False)
-        except ValueError:
-            return False
-    if host.endswith("*"):
-        # STRING prefix match (not CIDR). client_host is always the numeric
-        # socket peer IP (never a resolvable hostname), and a dotted prefix like
-        # "192.168." rejects "192.1680.x". Prefer CIDR (192.168.0.0/16) for
-        # unambiguous network matching; wildcards are a convenience.
-        return client_host.startswith(host[:-1])
-    return host == client_host
-
-
-def is_lan_client_allowed(client_host: str) -> bool:
-    """True iff remote mode is ON and ``client_host`` is in the trusted allowlist.
-
-    Loopback is handled separately by callers — this governs *non*-loopback LAN
-    clients only. Returns False whenever remote mode is off or the allowlist is
-    empty, so the default posture stays loopback-only.
-    """
-    if not is_remote_mode() or not client_host:
-        return False
-    entries = _allowlist_entries()
-    if not entries:
-        return False
-    try:
-        client_ip = ipaddress.ip_address(client_host)
-    except ValueError:
-        client_ip = None
-    return any(_host_matches(e, client_host, client_ip) for e in entries)
-
-
-def is_remote_origin_allowed(origin: str) -> bool:
-    """True iff remote mode is ON and ``origin``'s host is in the allowlist.
-
-    ``origin`` is a full URL (``http://192.168.50.144:8765``). Empty origin is
-    not this function's concern (loopback callers handle that). Used to relax
-    the dashboard CSRF origin guard for trusted LAN dashboards.
-    """
-    if not is_remote_mode() or not origin:
-        return False
-    # Extract host from scheme://host[:port]
-    rest = origin.split("://", 1)[-1]
-    host = rest.split("/", 1)[0]
-    # Strip a trailing :port (IPv4/hostname); leave bracketed IPv6 alone.
-    if host.startswith("["):
-        host = host.split("]", 1)[0].lstrip("[")
-    elif host.count(":") == 1:
-        host = host.split(":", 1)[0]
-    return is_lan_client_allowed(host)
-
-
-def _env_int(name: str, default: int) -> int:
-    """Read a positive int from env, falling back to ``default`` on any error."""
-    raw = os.environ.get(name, "").strip()
-    if not raw:
-        return default
-    try:
-        val = int(raw)
-    except ValueError:
-        return default
-    return val if val > 0 else default
-
-
-def rate_limit_config() -> tuple[int, int, int]:
-    """(write_max, read_max, window_seconds) for the dashboard rate limiter.
-
-    Issue #40 Issue 3: the limiter was hardcoded (30 writes / 120 reads per 60s)
-    with no way to raise it for distributed/LAN debugging, so a remote browser
-    that retried a failing Brain load hit ``429 Too Many Requests``. These are
-    now tunable via ``SLM_RATE_LIMIT_WRITE`` / ``SLM_RATE_LIMIT_READ`` /
-    ``SLM_RATE_LIMIT_WINDOW`` (defaults unchanged for the local case).
-    """
-    write_max = _env_int("SLM_RATE_LIMIT_WRITE", 30)
-    read_max = _env_int("SLM_RATE_LIMIT_READ", 120)
-    window = _env_int("SLM_RATE_LIMIT_WINDOW", 60)
-    return write_max, read_max, window
-
-
-def is_rate_limit_exempt(client_host: str) -> bool:
-    """True iff ``client_host`` should bypass the dashboard rate limiter.
-
-    Loopback is always exempt (the dashboard polls itself rapidly). In remote
-    mode, an allowlisted LAN client is the user's own remote browser doing the
-    same rapid reads, so it is exempt too — otherwise normal dashboard polling
-    trips the limiter (issue #40 Issue 3).
-    """
-    from superlocalmemory.server.loopback import is_loopback as _is_loopback_host
-
-    if _is_loopback_host(client_host):
-        return True
-    return is_lan_client_allowed(client_host)
-
-
-__all__ = (
-    "is_remote_mode",
-    "mcp_stateless",
-    "is_lan_client_allowed",
-    "is_remote_origin_allowed",
-    "rate_limit_config",
-    "is_rate_limit_exempt",
-)

package/src/superlocalmemory/core/reranker_worker.py

@@ -1,338 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Subprocess reranker worker — isolates PyTorch/ONNX from main process.
-
-Same pattern as embedding_worker.py. The main process stays at ~60 MB.
-All cross-encoder model memory lives in this worker subprocess.
-
-Protocol (JSON over stdin/stdout):
-  Request:  {"cmd": "rerank", "query": "...", "documents": ["...", ...]}
-  Response: {"ok": true, "scores": [0.95, 0.32, ...]}
-
-  Request:  {"cmd": "score", "query": "...", "document": "..."}
-  Response: {"ok": true, "score": 0.87}
-
-  Request:  {"cmd": "ping"}
-  Response: {"ok": true, "backend": "onnx", "model": "..."}
-
-  Request:  {"cmd": "quit"}
-  (worker exits)
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import platform
-import signal
-import struct
-import sys
-
-# Force CPU BEFORE any torch import
-os.environ["CUDA_VISIBLE_DEVICES"] = ""
-os.environ["PYTORCH_MPS_HIGH_WATERMARK_RATIO"] = "0.0"
-os.environ["PYTORCH_MPS_MEM_LIMIT"] = "0"
-os.environ["PYTORCH_ENABLE_MPS_FALLBACK"] = "1"
-os.environ["TOKENIZERS_PARALLELISM"] = "false"
-os.environ["TORCH_DEVICE"] = "cpu"
-# V3.3.17: Disable CoreML EP for ONNX Runtime. CoreML compiles execution
-# plans that consume 3-5GB on ARM64 Mac. CPU EP is ~500MB and fast enough.
-os.environ["ORT_DISABLE_COREML"] = "1"
-
-# SIGTERM bridge for Docker/systemd
-if sys.platform != "win32":
-    signal.signal(signal.SIGTERM, lambda *_: sys.exit(0))
-
-
-def _start_parent_watchdog() -> None:
-    """Monitor parent process — self-terminate if parent dies.
-
-    V3.4.24: Delegates to platform_utils.start_parent_watchdog().
-    """
-    from superlocalmemory.core.platform_utils import start_parent_watchdog
-    start_parent_watchdog()
-
-
-def _detect_onnx_variant(model_name: str = "") -> str:
-    """Auto-detect the best ONNX model variant for the current platform.
-
-    V3.4.2: Supports both legacy ms-marco-MiniLM (platform-specific quantized)
-    and new gte-modernbert-base (int8/uint8 quantized). Falls back to generic
-    model.onnx if platform-specific variant unavailable.
-    """
-    arch = platform.machine().lower()
-    is_64bit = struct.calcsize("P") * 8 == 64
-
-    # Legacy ms-marco-MiniLM models have platform-specific quantized variants
-    if "ms-marco" in model_name or "MiniLM" in model_name:
-        if sys.platform == "darwin" and arch in ("arm64", "aarch64"):
-            return "onnx/model_qint8_arm64.onnx"
-        if arch in ("x86_64", "amd64") and is_64bit:
-            return "onnx/model_quint8_avx2.onnx"
-        return "onnx/model.onnx"
-
-    # gte-modernbert-base and other modern models: int8 for ARM64, uint8 for x86
-    if sys.platform == "darwin" and arch in ("arm64", "aarch64"):
-        return "onnx/model_int8.onnx"
-    if arch in ("x86_64", "amd64") and is_64bit:
-        return "onnx/model_uint8.onnx"
-    return "onnx/model.onnx"
-
-
-def _worker_main() -> None:
-    """Main loop: read JSON requests from stdin, write responses to stdout."""
-    _start_parent_watchdog()
-    from superlocalmemory.core.platform_utils import get_rss_mb
-
-    model = None
-    active_backend = ""
-    model_name = ""
-
-    for line in sys.stdin:
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            req = json.loads(line)
-        except json.JSONDecodeError:
-            _respond({"ok": False, "error": "Invalid JSON"})
-            continue
-
-        cmd = req.get("cmd", "")
-
-        if cmd == "quit":
-            break
-
-        if cmd == "ping":
-            _respond({
-                "ok": True,
-                "loaded": model is not None,
-                "backend": active_backend,
-                "model": model_name,
-            })
-            continue
-
-        if cmd == "load":
-            name = req.get("model_name", "cross-encoder/ms-marco-MiniLM-L-12-v2")
-            backend = req.get("backend", "onnx")
-            model, active_backend, model_name, load_error = _load_model(
-                name, backend,
-            )
-            # V3.3.16: Run real inference to trigger ONNX CoreML JIT compilation.
-            # Without this, first real rerank call triggers 30-60s compilation
-            # that exceeds the caller's timeout, killing the worker.
-            warmup_ok = False
-            if model is not None:
-                try:
-                    # Use 60 pairs (realistic batch size) to trigger CoreML
-                    # compilation for the actual workload. 3 pairs compiled a
-                    # different execution plan that got recompiled on 60 pairs.
-                    dummy_pairs = [
-                        (f"What happened to person {i}?", f"Person {i} went to location {i} and did activity {i} last summer with friends.")
-                        for i in range(60)
-                    ]
-                    try:
-                        import torch
-                        with torch.inference_mode():
-                            _scores = model.predict(dummy_pairs)
-                    except ImportError:
-                        _scores = model.predict(dummy_pairs)
-                    warmup_ok = True
-                except Exception:
-                    pass
-            _respond({
-                "ok": model is not None,
-                "backend": active_backend,
-                "model": model_name,
-                "warmup_inference": warmup_ok,
-                # Carries the real reason to the parent so the warmup log can
-                # print it instead of a generic timeout message (issue #103).
-                "error": load_error,
-            })
-            continue
-
-        if cmd == "rerank":
-            query = req.get("query", "")
-            documents = req.get("documents", [])
-            if not query or not documents:
-                _respond({"ok": False, "error": "Missing query or documents"})
-                continue
-            if model is None:
-                # Auto-load with defaults
-                name = req.get("model_name", "cross-encoder/ms-marco-MiniLM-L-12-v2")
-                backend = req.get("backend", "onnx")
-                model, active_backend, model_name, load_error = _load_model(
-                    name, backend,
-                )
-            if model is None:
-                _respond({
-                    "ok": False,
-                    "error": load_error or "Model load failed",
-                })
-                continue
-            try:
-                pairs = [(query, doc) for doc in documents]
-                try:
-                    import torch
-                    with torch.inference_mode():
-                        scores = model.predict(pairs)
-                except ImportError:
-                    scores = model.predict(pairs)
-                _respond({
-                    "ok": True,
-                    "scores": [float(s) for s in scores],
-                })
-            except Exception as exc:
-                _respond({"ok": False, "error": str(exc)})
-
-            # V3.3.16: RSS watchdog — V3.4.24: cross-platform via platform_utils.
-            rss_mb = get_rss_mb()
-            if rss_mb > 0 and rss_mb > 2500:
-                sys.exit(0)
-
-            continue
-
-        if cmd == "score":
-            query = req.get("query", "")
-            document = req.get("document", "")
-            if not query or not document:
-                _respond({"ok": False, "error": "Missing query or document"})
-                continue
-            if model is None:
-                name = req.get("model_name", "cross-encoder/ms-marco-MiniLM-L-12-v2")
-                backend = req.get("backend", "onnx")
-                model, active_backend, model_name, load_error = _load_model(
-                    name, backend,
-                )
-            if model is None:
-                _respond({
-                    "ok": False,
-                    "error": load_error or "Model load failed",
-                })
-                continue
-            try:
-                try:
-                    import torch
-                    with torch.inference_mode():
-                        scores = model.predict([(query, document)])
-                except ImportError:
-                    scores = model.predict([(query, document)])
-                _respond({"ok": True, "score": float(scores[0])})
-            except Exception as exc:
-                _respond({"ok": False, "error": str(exc)})
-            continue
-
-        _respond({"ok": False, "error": f"Unknown command: {cmd}"})
-
-
-_KNOWN_BACKENDS = ("onnx", "", "pytorch", "torch")
-# Backends this worker can never serve — they are handled over HTTP by
-# superlocalmemory.retrieval.remote_reranker in the parent process (#105).
-# Duplicated as a literal on purpose: this module runs as a bare subprocess
-# and must not import the retrieval package (or, transitively, httpx).
-_REMOTE_BACKENDS = ("openai", "remote")
-
-
-def _load_model(
-    name: str, backend: str,
-) -> tuple:
-    """Load cross-encoder model. Returns (model, backend_name, model_name, error).
-
-    V3.3.13: sentence-transformers 5.x+ supports backend='onnx' for
-    CrossEncoder. We use a 3-tier fallback chain:
-
-      1. ONNX + platform-quantized model (fastest, ~200MB, 2.4ms/pair)
-      2. ONNX + generic model (fast, auto-exported on first use)
-      3. PyTorch (always works, ~500MB, 6ms/pair)
-
-    Cross-platform:
-      Mac ARM64 → model_qint8_arm64.onnx
-      x86_64    → model_quint8_avx2.onnx
-      Fallback  → model.onnx (generic)
-    """
-    # v3.8.11 (issue #103): an unrecognised backend used to fall through to
-    # the PyTorch tier and fail there with a confusing model-load error. A
-    # user who set backend="openai" expecting a remote reranker got five
-    # silent failures and no hint that the value meant nothing. Name it.
-    #
-    # v3.8.12 (issue #105): remote reranking now EXISTS, but it is served in
-    # the parent process — this worker holds torch/ONNX and cannot forward an
-    # HTTP request. Reaching here with a remote backend means the parent
-    # routed wrong (or a caller drove the worker directly), so the message
-    # points at the config keys that select the remote path.
-    if backend in _REMOTE_BACKENDS:
-        return None, "", "", (
-            f"unknown backend {backend!r} for the LOCAL reranker worker. "
-            f"{backend!r} selects the remote reranker, which runs in the "
-            f"parent process — set retrieval.cross_encoder_endpoint (e.g. "
-            f"\"http://127.0.0.1:8041/v1/rerank\") so SuperLocalMemory routes "
-            f"reranking over HTTP instead of spawning this worker."
-        )
-    if backend not in _KNOWN_BACKENDS:
-        return None, "", "", (
-            f"unknown backend {backend!r}; supported values are 'onnx' or ''"
-            f" (PyTorch) for local reranking, or 'openai'/'remote' with "
-            f"retrieval.cross_encoder_endpoint set for a remote "
-            f"OpenAI-compatible /v1/rerank endpoint."
-        )
-
-    tier_errors: list[str] = []
-    try:
-        from sentence_transformers import CrossEncoder
-
-        if backend == "onnx":
-            # Tier 1: Platform-specific quantized ONNX (fastest)
-            try:
-                onnx_file = _detect_onnx_variant(name)
-                m = CrossEncoder(
-                    name, backend="onnx",
-                    model_kwargs={"file_name": onnx_file},
-                )
-                return m, f"onnx-quantized({onnx_file})", name, ""
-            except Exception as exc:
-                tier_errors.append(f"onnx-quantized: {exc}")
-
-            # Tier 2: Generic ONNX (auto-exported by optimum)
-            try:
-                m = CrossEncoder(name, backend="onnx")
-                return m, "onnx", name, ""
-            except Exception as exc:
-                tier_errors.append(f"onnx: {exc}")
-
-        # Tier 3: PyTorch (always works, no ONNX dependency needed)
-        m = CrossEncoder(name)
-        return m, "pytorch", name, ""
-    except ImportError as exc:
-        # Previously indistinguishable from a bad model name.
-        return None, "", "", (
-            f"sentence-transformers is not installed ({exc}); "
-            f"install it or set retrieval.use_cross_encoder=false"
-        )
-    except Exception as exc:
-        tier_errors.append(f"pytorch: {exc}")
-        # Every tier's real error, propagated instead of discarded. Before
-        # 3.8.11 this returned (None, "", "") and the operator saw only a
-        # generic "did not confirm ready" line from the parent process.
-        return None, "", "", (
-            f"could not load cross-encoder model {name!r} "
-            f"(backend={backend or 'pytorch'}): " + "; ".join(tier_errors)
-        )
-
-
-def _respond(data: dict) -> None:
-    """Write JSON response to stdout, flush immediately."""
-    sys.stdout.write(json.dumps(data) + "\n")
-    sys.stdout.flush()
-
-
-if __name__ == "__main__":
-    try:
-        _worker_main()
-    except KeyboardInterrupt:
-        # V3.3.13: Windows CI sends KeyboardInterrupt on test completion.
-        # Exit cleanly instead of printing a traceback that fails CI.
-        sys.exit(0)

package/src/superlocalmemory/core/safe_fs.py

@@ -1,108 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Filesystem safety helpers for SQLite DB open paths.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-"""
-
-from __future__ import annotations
-
-import os
-import sqlite3
-import stat
-import sys
-from pathlib import Path
-
-
-class SafeFsError(RuntimeError):
-    """Raised when a data-directory or DB-open precondition fails."""
-
-
-_FORBIDDEN_COMPONENTS = (
-    "iCloud Drive", "Mobile Documents", "CloudDocs",
-    "Dropbox", "Google Drive", "OneDrive", "Box Sync",
-    # macOS 13+ canonical cloud-storage mount point. Every modern
-    # Dropbox / OneDrive / Google Drive / Box install on macOS routes
-    # through here, bypassing the brand-name checks above.
-    "Library/CloudStorage",
-)
-
-
-def validate_data_dir(path: Path) -> None:
-    """Refuse paths that live under a cloud-sync folder.
-
-    Cloud-synced directories silently corrupt SQLite WAL files.
-    """
-    resolved = str(path.resolve())
-    lowered = resolved.lower()
-    for comp in _FORBIDDEN_COMPONENTS:
-        if comp.lower() in lowered:
-            raise SafeFsError(
-                f"SLM data directory {resolved} appears to live under "
-                f"{comp!r} — cloud-synced folders are not supported "
-                f"(SQLite WAL corrupts silently on replication). "
-                f"Set SLM_DATA_DIR to a local path such as "
-                f"{Path.home()}/.slm-local"
-            )
-
-
-def _ensure_parent_0700(path: Path) -> None:
-    parent = path.parent
-    if not parent.exists():
-        parent.mkdir(parents=True, exist_ok=True)
-    if sys.platform == "win32":
-        return
-    st = parent.stat()
-    if st.st_uid != os.getuid():
-        raise SafeFsError(
-            f"{parent} is not owned by current user (uid={os.getuid()})"
-        )
-    if (st.st_mode & 0o077) != 0:
-        os.chmod(parent, 0o700)
-
-
-def _safe_open_db(path: Path) -> sqlite3.Connection:
-    """Open a SQLite DB with TOCTOU-tight symlink protection.
-
-    Pattern:
-      1. Enforce parent directory 0700.
-      2. lstat the DB path; refuse if it's already a symlink.
-      3. Open with O_NOFOLLOW to catch a last-moment swap.
-      4. fstat and compare inode with the pre-open lstat.
-      5. Close the fd and let sqlite3.connect reopen by path so WAL
-         and SHM sibling files can be created naturally.
-    """
-    _ensure_parent_0700(path)
-    if sys.platform != "win32":
-        if path.exists():
-            pre_st = os.lstat(str(path))
-            if stat.S_ISLNK(pre_st.st_mode):
-                raise SafeFsError(f"{path} is a symlink — refused")
-            if pre_st.st_uid != os.getuid():
-                raise SafeFsError(f"{path} not owned by current user")
-            if (pre_st.st_mode & 0o077) != 0:
-                os.chmod(str(path), 0o600)
-        else:
-            pre_st = None
-        try:
-            flags = os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW
-            fd = os.open(str(path), flags, 0o600)
-        except OSError as exc:
-            raise SafeFsError(f"Cannot safely open {path}: {exc}") from exc
-        try:
-            post_st = os.fstat(fd)
-            if pre_st is not None and (
-                (pre_st.st_ino, pre_st.st_dev)
-                != (post_st.st_ino, post_st.st_dev)
-            ):
-                raise SafeFsError(
-                    f"{path} changed between lstat and open — refused"
-                )
-        finally:
-            os.close(fd)
-    conn = sqlite3.connect(
-        str(path), isolation_level=None, timeout=5.0, check_same_thread=False,
-    )
-    return conn