java-codebase-rag 0.11.2__py3-none-any.whl → 0.12.1__py3-none-any.whl

java_codebase_rag/watch/client.py

@@ -1,230 +0,0 @@
-"""IPC client for the ``jrag watch`` daemon: try-the-daemon, cold-fall-back.
-
-The cold read path is BYTE-IDENTICAL to today: when no daemon is alive (the
-common case — including every ``jrag`` subprocess invocation that is not a
-``jrag watch`` process), :func:`get_payload` falls back to the same
-``<cmd>_payload`` core the handler already calls, loading the graph via
-``_load_graph(cfg)`` (a cache hit on the already-loaded singleton). The daemon
-is a pure accelerator: it never changes observable output, only latency.
-
-Contract (pinned by task-8 brief):
-
-* :func:`is_daemon_alive` -> ``socket_path`` exists AND
-  :meth:`ProjectLock.read_holder` returns a live pid.
-* :func:`request` -> ``response.result`` dict; raises :class:`DaemonUnavailable`
-  (no daemon / version mismatch / hung) or :class:`DaemonError` (``ok=False``).
-* :func:`get_payload` -> the single seam each read handler calls. Tries the
-  daemon; on :class:`DaemonUnavailable`/:class:`DaemonError` runs the cold
-  ``cold_core(argparse.Namespace(**args), cfg, _load_graph(cfg))``. On success it
-  RECONSTRUCTS the payload object from the daemon's serialized dict so the
-  handler's downstream project+render runs unchanged.
-
-Reconstruction is the lossless inverse of :func:`watch.server.serialize`:
-pydantic ``*Output`` models round-trip via ``model_dump(mode="json")`` /
-``model_validate``; the traversal payloads (callers/callees/flow) are plain
-dicts and pass through. The one non-pydantic case is ``find`` query mode, whose
-``rows`` are :class:`SymbolHit` dataclasses accessed by attribute in the renderer
-(``row.id``); those are rebuilt via ``SymbolHit(**row)`` so the renderer is
-untouched. (The task-8 brief literal said "pass-through" for query mode; that
-would break the renderer's attribute access on the hot path, so the rows are
-rebuilt instead — see task-8 report.)
-"""
-from __future__ import annotations
-
-import socket
-from typing import TYPE_CHECKING, Any, Callable
-
-from java_codebase_rag.jrag import _load_graph
-from java_codebase_rag.watch.lock import ProjectLock
-from java_codebase_rag.watch.paths import socket_path
-from java_codebase_rag.watch.protocol import (
-    PROTOCOL_VERSION,
-    ProtocolMismatch,
-    Request,
-    decode_response,
-    encode_request,
-)
-
-if TYPE_CHECKING:
-    from pathlib import Path
-
-# Connect/read budget so a hung daemon falls back to cold rather than blocking
-# the read command. 2s is generous for a local AF_UNIX round trip (the daemon
-# answers inline; a healthy response is sub-millisecond).
-_DAEMON_TIMEOUT = 2.0
-
-
-class DaemonUnavailable(Exception):
-    """No live daemon, an unreachable/hung daemon, or a protocol-version mismatch.
-
-    Always triggers the cold fallback in :func:`get_payload`.
-    """
-
-
-class DaemonError(Exception):
-    """The daemon answered ``ok=False`` (e.g. ``backend_error`` / ``stale_index``).
-
-    Attributes:
-        kind: the ``Response.error.kind`` string (``"backend_error"`` etc.).
-        message: the ``Response.error.message`` string.
-    """
-
-    def __init__(self, kind: str, message: str) -> None:
-        self.kind = kind
-        self.message = message
-        super().__init__(f"{kind}: {message}")
-
-
-def is_daemon_alive(index_dir: "Path") -> bool:
-    """True iff the daemon's socket exists AND a live holder pid is recorded.
-
-    The pid check (:meth:`ProjectLock.read_holder`) returns ``None`` for a
-    missing/empty pid file or a dead/stale pid, so a leftover socket alone does
-    not count as "alive" — a crashed daemon's socket is ignored and the read
-    falls back to cold.
-    """
-    if not socket_path(index_dir).exists():
-        return False
-    return ProjectLock.read_holder(index_dir) is not None
-
-
-def request(index_dir: "Path", cmd: str, args: dict) -> dict:
-    """Send one command to the daemon and return its ``result`` payload dict.
-
-    Raises:
-        DaemonUnavailable: not alive, unreachable/hung (timeout), closed
-            mid-response, or speaking a different protocol version (an older
-            daemon). All of these trigger the cold fallback.
-        DaemonError: the daemon responded ``ok=False``.
-    """
-    if not is_daemon_alive(index_dir):
-        raise DaemonUnavailable(f"no live daemon for {index_dir}")
-
-    sock_path = socket_path(index_dir)
-    try:
-        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
-            sock.settimeout(_DAEMON_TIMEOUT)
-            sock.connect(str(sock_path))
-            sock.sendall(encode_request(Request(v=PROTOCOL_VERSION, cmd=cmd, args=args)))
-            line = _readline(sock)
-    except OSError as exc:
-        # Timeout, connection refused, etc. -> cold fallback (never block).
-        raise DaemonUnavailable(f"daemon unreachable at {sock_path}: {exc}") from exc
-
-    try:
-        response = decode_response(line)
-    except (ProtocolMismatch, ValueError) as exc:
-        # Version mismatch (older daemon) or a blank/partial line (daemon gone)
-        # -> cold fallback rather than crashing the read command.
-        raise DaemonUnavailable(f"daemon response undecodable: {exc}") from exc
-
-    if not response.ok:
-        err = response.error
-        raise DaemonError(
-            err.kind if err is not None else "unknown",
-            err.message if err is not None else "",
-        )
-    return response.result
-
-
-def get_payload(cmd: str, args: dict, cfg, *, cold_core: Callable[..., Any]) -> Any:
-    """Return the payload for ``cmd``, trying the daemon first then cold-falling-back.
-
-    ``args`` is the command's full parsed-namespace dict (``vars(args)``);
-    ``cold_core`` is the matching ``<cmd>_payload(args, cfg, graph)`` core.
-
-    * Daemon success: the serialized payload dict is RECONSTRUCTED into the same
-      object the cold core returns, so the handler's render path is unchanged.
-    * DaemonUnavailable / DaemonError: the cold core runs against
-      ``_load_graph(cfg)`` — byte-identical to today (the daemon is absent in
-      every non-``watch`` invocation, and an ``ok=False`` frame re-surfaces as
-      the cold core's own ``PayloadError`` → identical error envelope + rc).
-    """
-    try:
-        result = request(cfg.index_dir, cmd, args)
-    except (DaemonUnavailable, DaemonError):
-        return cold_core(argparse_namespace(args), cfg, _load_graph(cfg))
-    return _reconstruct(cmd, result)
-
-
-# ---------------------------------------------------------------------------
-# internals
-# ---------------------------------------------------------------------------
-
-
-def _readline(sock: socket.socket) -> bytes:
-    """Read until newline (the response is one NDJSON line). Returns whatever was
-    received before newline/EOF; the caller decodes (and maps blanks to
-    ``DaemonUnavailable``)."""
-    buf = b""
-    while b"\n" not in buf:
-        chunk = sock.recv(4096)
-        if not chunk:
-            break
-        buf += chunk
-    return buf
-
-
-def _reconstruct(cmd: str, result: Any) -> Any:
-    """Rebuild the payload object the cold core returns from the daemon's JSON dict.
-
-    Inverse of :func:`watch.server.serialize`. See module docstring for the
-    find query-mode ``SymbolHit`` rebuild rationale.
-    """
-    if cmd == "search":
-        from java_codebase_rag.mcp.mcp_v2 import SearchOutput
-
-        return SearchOutput.model_validate(result)
-
-    if cmd == "inspect":
-        from java_codebase_rag.mcp.mcp_v2 import DescribeOutput
-
-        return {
-            "describe": DescribeOutput.model_validate(result["describe"]),
-            "node_id": result["node_id"],
-            "node_fqn": result["node_fqn"],
-            "file_location": result["file_location"],
-        }
-
-    if cmd == "find":
-        # The find payload is always a {"mode": "query"|"filter", ...} dict.
-        mode = result.get("mode")
-        if mode == "filter":
-            from java_codebase_rag.mcp.mcp_v2 import FindOutput
-
-            return {
-                "mode": "filter",
-                "kind": result["kind"],
-                "out": FindOutput.model_validate(result["out"]),
-                "limit": result["limit"],
-            }
-        # query mode: rows are SymbolHit dataclasses (attribute access in the
-        # renderer), rebuilt here so rendering is byte-identical.
-        from java_codebase_rag.graph.ladybug_queries import SymbolHit
-
-        return {
-            "mode": "query",
-            "rows": [SymbolHit(**row) for row in result["rows"]],
-            "raw_truncated": result["raw_truncated"],
-            "post_filter_active": result["post_filter_active"],
-            "limit": result["limit"],
-            "query": result["query"],
-            "kinds": result["kinds"],
-            "matched_mode": result["matched_mode"],
-            "identifier_matched": result["identifier_matched"],
-        }
-
-    # callers / callees / flow: plain dicts already (node/edge values are dicts
-    # of JSON-native scalars); pass through unchanged.
-    return result
-
-
-def argparse_namespace(args: dict):
-    """Build an ``argparse.Namespace`` from the args dict (deferred import).
-
-    Imported lazily so this module's top level stays free of the ``argparse``
-    dependency needed only on the cold path; also a single seam for the cold
-    core's ``args`` reconstruction."""
-    import argparse
-
-    return argparse.Namespace(**args)

java_codebase_rag/watch/daemon.py

@@ -1,396 +0,0 @@
-"""The ``jrag watch`` daemon process: assemble the watch components and run them.
-
-``WatchDaemon`` is the capstone that wires together the building blocks built in
-Tasks 2-10:
-
-  * :class:`watch.lock.ProjectLock` — single-writer mutual exclusion per project.
-  * :class:`watch.warm.WarmResources` — the warm embedding model + the read-only
-    graph reader (and the graph copy-on-write snapshot lifecycle).
-  * :class:`watch.server.WatchServer` — the AF_UNIX socket server that dispatches
-    read commands to the payload cores and ships the serialized payload.
-  * :class:`watch.watcher.SourceWatcher` — the file watcher + debounced per-type
-    reindex dispatcher.
-
-Lifecycle (``run_foreground``):
-
-  1. Acquire the project lock. Held elsewhere -> stderr line + ``return 2``.
-     Unsupported platform -> stderr line + ``return 2``.
-  2. EAGERLY warm the embedding model — but ONLY when the vector stack is
-     installed — so a load failure fails fast (stderr + ``on_event("error", …)``
-     + lock release + ``return 2``). On graph-only installs (macOS Intel: PEP
-     508 excludes sentence_transformers/lancedb) this step is skipped and the
-     daemon serves warm lexical/graph-only search instead; the read path
-     (``mcp_v2.search_v2``) degrades to lexical on its own.
-  3. Install SIGINT/SIGTERM handlers that set a stop flag.
-  4. ``server.start()`` then ``watcher.start()``.
-  5. Write the state file (``paths.state_path``) so ``--status``/``--stop`` from
-     another process can see current truth.
-  6. Render a ``rich`` Live status panel (watcher state, last reindex) and
-     block on a wait loop until the stop flag is set.
-  7. Tear down in order — ``watcher.stop()`` → ``server.shutdown()`` →
-     ``lock.release()`` → unlink socket + state file — and terminate with
-     ``os._exit(0)``. The explicit ``os._exit`` (mirroring
-     ``jrag._console_script_main``) skips interpreter finalization, which dodges
-     a racy pyarrow/lance worker-thread SIGABRT once the daemon has served a
-     ``search`` (the read path loads lancedb in-process). ``run_foreground``
-     therefore NEVER returns normally on the serving path.
-"""
-from __future__ import annotations
-
-import json
-import logging
-import os
-import signal
-import sys
-import threading
-import time
-from typing import TYPE_CHECKING, Any
-
-from java_codebase_rag.pipeline import vector_stack_installed
-from java_codebase_rag.watch import paths
-from java_codebase_rag.watch.lock import (
-    LockHeldError,
-    ProjectLock,
-    WatchUnsupportedPlatform,
-)
-from java_codebase_rag.watch.server import WatchServer
-from java_codebase_rag.watch.warm import WarmResources
-from java_codebase_rag.watch.watcher import SourceWatcher
-
-if TYPE_CHECKING:
-    from java_codebase_rag.config import ResolvedOperatorConfig
-
-# State-file rewrites are throttled so a busy reindex burst does not hammer disk.
-# The initial write (``force=True``) and the last reindex both go through
-# immediately; ``--status`` readers tolerate a slightly-stale ``last_reindex``.
-_STATE_WRITE_MIN_INTERVAL_S = 1.0
-# The blocking loop's tick: how often the Live panel refreshes and how quickly a
-# stop signal is observed. 0.5 s is responsive without burning CPU.
-_LOOP_TICK_S = 0.5
-
-log = logging.getLogger(__name__)
-
-
-class WatchDaemon:
-    """Assemble the watch components and serve until interrupted.
-
-    The daemon process holds the project lock for its entire lifetime; the state
-    file is the cross-process truth that ``--status``/``--stop`` read.
-    """
-
-    def __init__(self, cfg: "ResolvedOperatorConfig") -> None:
-        self.cfg = cfg
-        # Probed once (cheap: 3x importlib.util.find_spec). When False (graph-only
-        # install — macOS Intel), the daemon skips the embedding-model warm-up and
-        # the cocoindex vectors reindex; the read path degrades to lexical on its own.
-        self._vector_enabled = vector_stack_installed()
-        self.lock = ProjectLock(cfg.index_dir)
-        self.warm = WarmResources(cfg)
-        self.server = WatchServer(self.warm, cfg)
-        self.watcher = SourceWatcher(
-            cfg,
-            self.warm,
-            debounce_ms=cfg.watch_debounce_ms,
-            backend=cfg.watch_backend,
-            poll_interval_ms=cfg.watch_poll_interval_ms,
-            on_event=self._record,
-        )
-
-        self._stop = threading.Event()
-        self._state_lock = threading.Lock()
-        self._last_state_write = 0.0
-        self._state: dict[str, Any] = {
-            "started_at": None,
-            "pid": None,
-            "socket": str(paths.socket_path(cfg.index_dir)),
-            # Display label derived from the install-time probe above, NOT a live
-            # search-capability check — the read path's actual lexical/vector choice
-            # is mcp_v2's (``_ensure_vector_backend``). The two agree under the PEP
-            # 508 markers (the vector trio is present or absent together). Surfaced
-            # in the status panel and ``jrag watch --status``; omitted from display
-            # on the normal (vector) path to avoid noise.
-            "mode": "lexical" if not self._vector_enabled else "vector",
-            "last_reindex_at": None,
-            "last_reindex_kind": None,
-            "reindex_count": 0,
-            # ``queries_served`` is left at 0 for v1: wiring a query-count
-            # callback out of ``WatchServer`` (Task 7, approved) is out of scope
-            # for this task's commit surface and the brief marks it optional.
-            "queries_served": 0,
-        }
-
-    # ------------------------------------------------------------------
-    # public lifecycle
-    # ------------------------------------------------------------------
-
-    def run_foreground(self) -> int:
-        """Serve until SIGINT/SIGTERM, then tear down and ``os._exit(0)``.
-
-        Early failure paths (lock held, unsupported platform, model-load error)
-        return ``2`` normally — they occur before the server accepts connections,
-        so no lance worker threads exist and interpreter finalization is safe.
-
-        The serving path (after ``server.start()``) terminates ONLY via
-        ``os._exit(0)`` in :meth:`_shutdown`; the trailing ``return 0`` is
-        unreachable and exists to satisfy the ``-> int`` contract.
-        """
-        # 1. Acquire the project lock (single writer per project).
-        try:
-            self.lock.acquire()
-        except LockHeldError as exc:
-            print(f"jrag watch: index in use by PID {exc.pid}", file=sys.stderr)
-            return 2
-        except WatchUnsupportedPlatform:
-            print("jrag watch: watch mode requires macOS/Linux", file=sys.stderr)
-            return 2
-
-        # 2. Eagerly warm the embedding model so a load failure fails fast (before
-        #    the server accepts a single query) — but ONLY when the vector stack is
-        #    installed. The model is the only heavy, failure-prone resource that is
-        #    not lazy on the read path. On a graph-only install (macOS Intel) there
-        #    is no vector stack to warm; the daemon serves lexical/graph-only search
-        #    and ``mcp_v2.search_v2`` degrades on its own, so we skip straight to
-        #    serving rather than failing on a missing ``sentence_transformers``.
-        if self._vector_enabled:
-            try:
-                self.warm.model()
-            except Exception as exc:  # noqa: BLE001 — report any load failure, then bail
-                print(f"jrag watch: failed to load embedding model: {exc}", file=sys.stderr)
-                self._record("error", {"phase": "model_load", "error": repr(exc)})
-                self.lock.release()
-                return 2
-        else:
-            print(
-                "jrag watch: vector stack unavailable — serving lexical (graph-only) search",
-                file=sys.stderr,
-            )
-
-        # 3. Install stop-signal handlers (main thread only).
-        signal.signal(signal.SIGINT, self._on_signal)
-        signal.signal(signal.SIGTERM, self._on_signal)
-
-        # 4a. Server start: bind the socket before starting the watcher so a
-        #     query the moment the panel renders is already servable.
-        #
-        # We hold the EXCLUSIVE project lock, so we are the unique legitimate
-        # owner of this socket path: any pre-existing socket file is a corpse
-        # from a crashed prior daemon and MUST be cleared before bind, else
-        # AF_UNIX bind() fails with EADDRINUSE. ``server.start`` also defends
-        # against a stale socket for callers that do NOT hold the lock, but its
-        # guard (``read_holder is None``) is inert here precisely because we
-        # hold the lock — so the daemon clears its own stale socket itself.
-        stale_sock = paths.socket_path(self.cfg.index_dir)
-        try:
-            stale_sock.unlink()
-        except FileNotFoundError:
-            pass
-        except OSError:
-            log.warning("could not unlink stale socket %s", stale_sock, exc_info=True)
-        try:
-            self.server.start()
-        except Exception as exc:  # noqa: BLE001 — socket bind failure is fatal-but-reported
-            print(f"jrag watch: failed to start server: {exc}", file=sys.stderr)
-            self.lock.release()
-            self._cleanup_runtime_files()
-            return 2
-        # 4b. Watcher start.
-        try:
-            self.watcher.start()
-        except Exception as exc:  # noqa: BLE001 — reported; server already up so shut it down
-            print(f"jrag watch: failed to start watcher: {exc}", file=sys.stderr)
-            self.server.shutdown()
-            self._cleanup_runtime_files()
-            self.lock.release()
-            return 2
-
-        # 5. Write the initial state file (force, so --status sees truth at once).
-        self._state["started_at"] = time.time()
-        self._state["pid"] = os.getpid()
-        self._write_state()
-
-        # 6 + 7. Serve, then tear down. _shutdown ends with os._exit(0) so the
-        #        finally never falls through; the return is unreachable.
-        try:
-            self._serve_until_stopped()
-        finally:
-            self._shutdown()
-        return 0  # pragma: no cover — os._exit in _shutdown
-
-    # ------------------------------------------------------------------
-    # event recording (called from the watcher debounce thread + the UI loop)
-    # ------------------------------------------------------------------
-
-    def _record(self, kind: str, detail: dict[str, Any]) -> None:
-        """Update in-memory state from a watcher event; throttle state rewrites.
-
-        Called on the watcher's debounce worker thread, so all state mutation is
-        under ``_state_lock``. The state file is rewritten at most once per
-        ``_STATE_WRITE_MIN_INTERVAL_S`` so ``--status`` readers see recent truth
-        without disk churn during a reindex burst.
-        """
-        with self._state_lock:
-            if kind == "indexing_done":
-                self._state["last_reindex_at"] = time.time()
-                self._state["last_reindex_kind"] = "+".join(detail.get("kinds", []))
-                self._state["reindex_count"] += 1
-            elif kind == "indexing_started":
-                self._state["last_reindex_kind"] = (
-                    "indexing:" + "+".join(detail.get("kinds", []))
-                )
-            elif kind == "error":
-                self._state["last_error"] = {
-                    "phase": detail.get("phase"),
-                    "at": time.time(),
-                    "detail": detail,
-                }
-            self._maybe_write_state_locked()
-
-    # ------------------------------------------------------------------
-    # serve loop + status panel
-    # ------------------------------------------------------------------
-
-    def _serve_until_stopped(self) -> None:
-        """Render the status panel and block until the stop flag is set.
-
-        On a non-TTY stdio (detached, piped, tests) the Live region is skipped in
-        favor of a single startup line — ``rich.Live`` on a pipe reprints the
-        whole panel on every update and would flood the redirect log.
-        """
-        from rich.console import Console
-
-        console = Console()
-        live = None
-        if console.is_terminal:
-            try:
-                from rich.live import Live
-
-                live = Live(
-                    self._render_panel(),
-                    console=console,
-                    refresh_per_second=4,
-                    transient=False,
-                )
-                live.start()
-            except Exception:  # noqa: BLE001 — Live is cosmetic; never block serving
-                live = None
-        if live is None:
-            print(
-                f"jrag watch: serving on {self._state['socket']} "
-                f"(pid {os.getpid()})",
-                flush=True,
-            )
-
-        try:
-            while not self._stop.is_set():
-                if live is not None:
-                    try:
-                        live.update(self._render_panel())
-                    except Exception:  # noqa: BLE001 — cosmetic
-                        pass
-                # Event.wait returns True as soon as the flag is set, so a stop
-                # signal is observed within one tick rather than the full window.
-                self._stop.wait(_LOOP_TICK_S)
-        finally:
-            if live is not None:
-                try:
-                    live.stop()
-                except Exception:  # noqa: BLE001 — cosmetic
-                    pass
-
-    def _render_panel(self):
-        """Build the ``rich`` status table from the current in-memory state."""
-        from rich.table import Table
-
-        with self._state_lock:
-            state = dict(self._state)
-        table = Table(title=f"jrag watch (pid {os.getpid()})", show_header=False, box=None)
-        table.add_row("socket", str(state.get("socket")))
-        if state.get("mode") == "lexical":
-            table.add_row("mode", "lexical (graph-only)")
-        table.add_row("reindex count", str(state.get("reindex_count", 0)))
-        last_kind = state.get("last_reindex_kind")
-        last_at = state.get("last_reindex_at")
-        if last_kind:
-            when = time.strftime("%H:%M:%S", time.localtime(last_at)) if last_at else "—"
-            table.add_row("last reindex", f"{last_kind} ({when})")
-        else:
-            table.add_row("last reindex", "—")
-        return table
-
-    # ------------------------------------------------------------------
-    # shutdown
-    # ------------------------------------------------------------------
-
-    def _shutdown(self) -> None:
-        """Tear down watcher → server → lock, remove runtime files, ``os._exit(0)``.
-
-        Each step is best-effort: a failure in one must not skip the rest, and
-        the process MUST terminate via ``os._exit(0)`` (never a normal return)
-        to avoid the lance worker-thread SIGABRT at finalization once the server
-        has served a ``search`` query.
-        """
-        try:
-            self.watcher.stop()
-        except Exception:  # noqa: BLE001 — teardown must continue
-            log.warning("watcher.stop raised during shutdown", exc_info=True)
-        try:
-            self.server.shutdown()
-        except Exception:  # noqa: BLE001
-            log.warning("server.shutdown raised during shutdown", exc_info=True)
-        try:
-            self.lock.release()
-        except Exception:  # noqa: BLE001
-            log.warning("lock.release raised during shutdown", exc_info=True)
-        self._cleanup_runtime_files()
-        sys.stdout.flush()
-        sys.stderr.flush()
-        os._exit(0)
-
-    # ------------------------------------------------------------------
-    # helpers
-    # ------------------------------------------------------------------
-
-    def _on_signal(self, signum, frame) -> None:  # noqa: ARG002 — signal API
-        """SIGINT/SIGTERM handler: flag the serve loop to stop (main thread)."""
-        self._stop.set()
-
-    def _cleanup_runtime_files(self) -> None:
-        """Remove the socket and state file (idempotent, best-effort)."""
-        for path in (
-            paths.socket_path(self.cfg.index_dir),
-            paths.state_path(self.cfg.index_dir),
-        ):
-            try:
-                path.unlink()
-            except FileNotFoundError:
-                pass
-            except OSError:
-                log.warning("could not unlink %s", path, exc_info=True)
-
-    def _write_state(self) -> None:
-        """Unconditionally write the state JSON now (initial write).
-
-        Acquires ``_state_lock``; the throttled re-write path is
-        :meth:`_maybe_write_state_locked`, called by :meth:`_record` which
-        already holds the lock.
-        """
-        with self._state_lock:
-            self._write_state_locked()
-
-    def _maybe_write_state_locked(self) -> None:
-        """Throttled state write; caller MUST hold ``_state_lock``."""
-        now = time.monotonic()
-        if now - self._last_state_write >= _STATE_WRITE_MIN_INTERVAL_S:
-            self._write_state_locked()
-
-    def _write_state_locked(self) -> None:
-        """Write the JSON state file (best-effort); caller MUST hold ``_state_lock``."""
-        path = paths.state_path(self.cfg.index_dir)
-        data = dict(self._state)
-        try:
-            tmp = path.with_suffix(path.suffix + ".tmp")
-            tmp.write_text(json.dumps(data))
-            os.replace(tmp, path)
-            self._last_state_write = time.monotonic()
-        except OSError:
-            log.warning("could not write state file %s", path, exc_info=True)