Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

43.1 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""
Resource monitoring task manager.

Provides task creation, update, deletion, query, and persistence storage.
"""

import json
import uuid
from datetime import datetime, timedelta
from typing import Any, Dict, List, Optional

from pydantic import BaseModel, Field

from openviking.concurrency import AsyncSemaphore
from openviking.observability.http_error_context import sanitize_public_http_error
from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.resource.uri_mutation_coordinator import (
    UriMutationCoordinator,
)
from openviking.resource.uri_mutation_coordinator import (
    uri_matches_prefix as _uri_matches_prefix,
)
from openviking.resource.watch_storage import (
    WATCH_TASK_STORAGE_BAK_URI,
    WATCH_TASK_STORAGE_TMP_URI,
    WATCH_TASK_STORAGE_URI,
)
from openviking_cli.exceptions import ConflictError, NotFoundError
from openviking_cli.utils.logger import get_logger

logger = get_logger(__name__)

_UNSET = object()


def _rewrite_uri_prefix(uri: str, old_prefix: str, new_prefix: str) -> str:
    old_normalized = old_prefix.rstrip("/")
    new_normalized = new_prefix.rstrip("/")
    if uri == old_normalized:
        return new_normalized
    return new_normalized + uri[len(old_normalized) :]


def _parent_uri(uri: str) -> Optional[str]:
    normalized = uri.rstrip("/")
    if "/" not in normalized:
        return None
    parent = normalized.rsplit("/", 1)[0]
    if parent in {"viking:/", "viking://"}:
        return None
    return parent


class WatchTask(BaseModel):
    """Resource monitoring task data model."""

    task_id: str = Field(
        default_factory=lambda: str(uuid.uuid4()), description="Unique task identifier"
    )
    path: str = Field(..., description="Resource path to monitor")
    source_type: Optional[str] = Field(None, description="Original resource source type")
    to_uri: Optional[str] = Field(None, description="Target URI")
    to_is_directory: Optional[bool] = Field(
        None,
        description="Whether the target URI is a directory destination",
    )
    parent_uri: Optional[str] = Field(None, description="Parent URI")
    reason: str = Field(default="", description="Reason for monitoring")
    instruction: str = Field(default="", description="Monitoring instruction")
    watch_interval: float = Field(default=60.0, description="Monitoring interval in minutes")
    build_index: bool = Field(default=True, description="Whether to build vector index")
    summarize: bool = Field(default=False, description="Whether to generate summary")
    processing_mode: ProcessingMode = Field(
        default=DEFAULT_PROCESSING_MODE,
        description="Post-ingest processing mode for scheduled add_resource runs",
    )
    processor_kwargs: Dict[str, Any] = Field(
        default_factory=dict, description="Extra kwargs forwarded to processor"
    )
    auth_state: Optional[Dict[str, Any]] = Field(
        default=None, description="Private authentication state for scheduled re-processing"
    )
    connector_states: Optional[Dict[str, Any]] = Field(
        default=None, description="Private external Connector stream states"
    )
    source_checkpoint: Optional[Dict[str, Any]] = Field(
        default=None,
        description=(
            "Private source version checkpoint used to skip unchanged refreshes, "
            "e.g. {'kind': 'git', 'head_sha': '<sha>', 'instruction': '<instruction>'}"
        ),
    )
    created_at: datetime = Field(default_factory=datetime.now, description="Task creation time")
    last_execution_time: Optional[datetime] = Field(None, description="Last execution time")
    last_task_id: Optional[str] = Field(None, description="Latest ingestion task identifier")
    last_status: Optional[str] = Field(None, description="Latest execution status")
    last_error: Optional[str] = Field(None, description="Latest sanitized execution error")
    next_execution_time: Optional[datetime] = Field(None, description="Next execution time")
    is_active: bool = Field(default=True, description="Whether the task is active")
    account_id: str = Field(default="default", description="Account ID (tenant)")
    user_id: str = Field(default="default", description="User ID who created this task")
    original_role: str = Field(default="user", description="Role used to execute this task")

    class Config:
        json_encoders = {datetime: lambda v: v.isoformat() if v else None}
        extra = "ignore"

    def to_dict(self) -> Dict[str, Any]:
        """Convert task to public dictionary."""
        return {
            "task_id": self.task_id,
            "path": self.path,
            "source_type": self.source_type,
            "to_uri": self.to_uri,
            "parent_uri": self.parent_uri,
            "reason": self.reason,
            "instruction": self.instruction,
            "watch_interval": self.watch_interval,
            "build_index": self.build_index,
            "summarize": self.summarize,
            "processing_mode": self.processing_mode,
            "processor_kwargs": self.processor_kwargs,
            "created_at": self.created_at.isoformat() if self.created_at else None,
            "last_execution_time": self.last_execution_time.isoformat()
            if self.last_execution_time
            else None,
            "last_task_id": self.last_task_id,
            "last_status": self.last_status,
            "last_error": self.last_error,
            "next_execution_time": self.next_execution_time.isoformat()
            if self.next_execution_time
            else None,
            "is_active": self.is_active,
            "account_id": self.account_id,
            "user_id": self.user_id,
            "original_role": self.original_role,
        }

    def to_storage_dict(self) -> Dict[str, Any]:
        """Convert task to dictionary for watch-task persistence."""
        data = self.to_dict()
        data["to_is_directory"] = self.to_is_directory
        if self.auth_state is not None:
            data["auth_state"] = self.auth_state
        if self.connector_states is not None:
            data["connector_states"] = self.connector_states
        if self.source_checkpoint is not None:
            data["source_checkpoint"] = self.source_checkpoint
        return data

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "WatchTask":
        """Create task from dictionary."""
        data = dict(data)
        if isinstance(data.get("created_at"), str):
            data["created_at"] = datetime.fromisoformat(data["created_at"])
        if isinstance(data.get("last_execution_time"), str):
            data["last_execution_time"] = datetime.fromisoformat(data["last_execution_time"])
        if isinstance(data.get("next_execution_time"), str):
            data["next_execution_time"] = datetime.fromisoformat(data["next_execution_time"])
        if data.get("processor_kwargs") is None:
            data["processor_kwargs"] = {}
        if data.get("auth_state") is not None and not isinstance(data.get("auth_state"), dict):
            data["auth_state"] = None
        if data.get("connector_states") is not None and not isinstance(
            data.get("connector_states"), dict
        ):
            data["connector_states"] = None
        if data.get("source_checkpoint") is not None and not isinstance(
            data.get("source_checkpoint"), dict
        ):
            data["source_checkpoint"] = None
        return cls(**data)

    def calculate_next_execution_time(self) -> datetime:
        """Calculate next execution time based on interval."""
        base_time = self.last_execution_time or self.created_at
        return base_time + timedelta(minutes=self.watch_interval)


class PermissionDeniedError(Exception):
    """Permission denied error for watch operations."""

    pass


class WatchManager:
    """Resource monitoring task manager.

    Provides task creation, update, deletion, query, and persistence storage.
    Thread-safe with async lock for concurrent access protection.
    Supports multi-tenant authorization.
    """

    STORAGE_URI = WATCH_TASK_STORAGE_URI
    STORAGE_BAK_URI = WATCH_TASK_STORAGE_BAK_URI
    STORAGE_TMP_URI = WATCH_TASK_STORAGE_TMP_URI

    def __init__(
        self,
        viking_fs: Optional[Any] = None,
        uri_mutation_coordinator: Optional[UriMutationCoordinator] = None,
    ):
        """Initialize WatchManager.

        Args:
            viking_fs: VikingFS instance for persistence storage
        """
        self._tasks: Dict[str, WatchTask] = {}
        # (account_id, to_uri) -> task ids. A native watch owns its target alone
        # (a refresh replaces the whole root); Connector watches write
        # ``to/<relative_path>`` and may share one target.
        self._uri_to_task: Dict[tuple[str, str], set[str]] = {}
        self._lock = AsyncSemaphore()
        self._uri_mutation_coordinator = uri_mutation_coordinator or UriMutationCoordinator()
        self._viking_fs = viking_fs
        self._initialized = False

    async def initialize(self) -> None:
        """Initialize the manager by loading tasks from storage."""
        if self._initialized:
            return

        async with self._lock:
            if self._initialized:
                return

            await self._load_tasks()
            self._initialized = True
            logger.info(f"[WatchManager] Initialized with {len(self._tasks)} tasks")

    async def _load_tasks(self) -> None:
        """Load tasks from VikingFS storage."""
        if not self._viking_fs:
            logger.debug("[WatchManager] No VikingFS provided, skipping load")
            return

        try:
            from openviking.server.identity import RequestContext, Role
            from openviking_cli.session.user_id import UserIdentifier

            ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)

            data = None
            try:
                content = await self._viking_fs.read_file(self.STORAGE_URI, ctx=ctx)
                if content and content.strip():
                    data = json.loads(content)
            except NotFoundError:
                data = None
            except json.JSONDecodeError as e:
                logger.warning(f"[WatchManager] Invalid task storage JSON: {e}")
            except Exception as e:
                logger.warning(f"[WatchManager] Failed to read task storage: {e}")

            recovered_from_backup = False
            if data is None:
                try:
                    bak_content = await self._viking_fs.read_file(self.STORAGE_BAK_URI, ctx=ctx)
                    if bak_content and bak_content.strip():
                        data = json.loads(bak_content)
                        recovered_from_backup = True
                except NotFoundError:
                    data = None
                except json.JSONDecodeError as e:
                    logger.warning(f"[WatchManager] Invalid backup task storage JSON: {e}")
                    data = None
                except Exception as e:
                    logger.warning(f"[WatchManager] Failed to read backup task storage: {e}")

            if not isinstance(data, dict):
                data = {"tasks": []}

            normalized = False
            for task_data in data.get("tasks", []):
                try:
                    task = WatchTask.from_dict(task_data)
                    if not task.is_active:
                        if task.next_execution_time is not None:
                            task.next_execution_time = None
                            normalized = True
                    else:
                        if task.watch_interval <= 0:
                            task.is_active = False
                            task.next_execution_time = None
                            normalized = True
                        elif task.next_execution_time is None:
                            task.next_execution_time = task.calculate_next_execution_time()
                            normalized = True
                    self._tasks[task.task_id] = task
                    self._index_add(task.account_id, task.to_uri, task.task_id)
                except Exception as e:
                    logger.warning(
                        f"[WatchManager] Failed to load task {task_data.get('task_id')}: {e}"
                    )

            logger.info(f"[WatchManager] Loaded {len(self._tasks)} tasks from storage")
            if recovered_from_backup:
                normalized = True
            if normalized:
                await self._save_tasks()
        except NotFoundError:
            logger.debug("[WatchManager] No existing task storage found, starting fresh")
        except Exception as e:
            logger.error(f"[WatchManager] Failed to load tasks: {e}")

    async def _save_tasks(self) -> None:
        """Save tasks to VikingFS storage."""
        if not self._viking_fs:
            logger.debug("[WatchManager] No VikingFS provided, skipping save")
            return

        try:
            from openviking.server.identity import RequestContext, Role
            from openviking_cli.session.user_id import UserIdentifier

            ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)

            data = {
                "tasks": [task.to_storage_dict() for task in self._tasks.values()],
                "updated_at": datetime.now().isoformat(),
            }

            content = json.dumps(data, ensure_ascii=False, indent=2)
            if not content.strip():
                raise ValueError("Refusing to write empty watch task storage")
            json.loads(content)

            supports_atomic = all(
                hasattr(self._viking_fs, name) for name in ("mv", "rm", "exists", "write_file")
            )
            if not supports_atomic:
                await self._viking_fs.write_file(self.STORAGE_URI, content, ctx=ctx)
                logger.debug(f"[WatchManager] Saved {len(self._tasks)} tasks to storage")
                return

            await self._viking_fs.write_file(self.STORAGE_TMP_URI, content, ctx=ctx)

            try:
                if await self._viking_fs.exists(self.STORAGE_BAK_URI, ctx=ctx):
                    await self._viking_fs.rm(self.STORAGE_BAK_URI, ctx=ctx)
            except Exception:
                pass

            try:
                if await self._viking_fs.exists(self.STORAGE_URI, ctx=ctx):
                    await self._viking_fs.mv(self.STORAGE_URI, self.STORAGE_BAK_URI, ctx=ctx)
            except Exception as e:
                logger.warning(f"[WatchManager] Failed to rotate task storage backup: {e}")

            await self._viking_fs.mv(self.STORAGE_TMP_URI, self.STORAGE_URI, ctx=ctx)
            logger.debug(f"[WatchManager] Saved {len(self._tasks)} tasks to storage")
        except Exception as e:
            logger.error(f"[WatchManager] Failed to save tasks: {e}")
            raise

    def _check_permission(
        self,
        task: WatchTask,
        account_id: str,
        user_id: str,
        role: str,
    ) -> bool:
        """Check if user has permission to access/modify a task.

        Args:
            task: The task to check permission for
            account_id: Requester's account ID
            user_id: Requester's user ID
            role: Requester's role (ROOT/ADMIN/USER)

        Returns:
            True if has permission, False otherwise

        Notes:
            - ROOT can access all tasks (system/scheduler bypass).
            - Every other role (including ADMIN) is scoped to tasks they own
              within the same account, so callers sharing an account but using
              different user_ids never see each other's tasks.
        """
        role_value = (role or "").lower()
        if role_value == "root":
            return True

        if task.account_id != account_id:
            return False

        return task.user_id == user_id

    # ── Target index helpers ─────────────────────────────────────────────

    def _index_get(self, account_id: str, to_uri: Optional[str]) -> set[str]:
        if not to_uri:
            return set()
        return set(self._uri_to_task.get((account_id, to_uri), ()))

    def _index_add(self, account_id: str, to_uri: Optional[str], task_id: str) -> None:
        if to_uri:
            self._uri_to_task.setdefault((account_id, to_uri), set()).add(task_id)

    def _index_remove(self, account_id: str, to_uri: Optional[str], task_id: str) -> None:
        if not to_uri:
            return
        ids = self._uri_to_task.get((account_id, to_uri))
        if ids is None:
            return
        ids.discard(task_id)
        if not ids:
            del self._uri_to_task[(account_id, to_uri)]

    @staticmethod
    def _is_connector_auth_state(auth_state: Optional[Dict[str, Any]]) -> bool:
        from openviking.connector.delegate import ConnectorDelegate

        return ConnectorDelegate.is_watch_auth_state(auth_state)

    def _all_connector_tasks(self, task_ids: set[str]) -> bool:
        if not task_ids or not task_ids <= self._tasks.keys():
            return False
        return all(
            self._is_connector_auth_state(self._tasks[task_id].auth_state) for task_id in task_ids
        )

    def _blocking_task_ids(
        self,
        to_uri: Optional[str],
        account_id: str,
        auth_state: Optional[Dict[str, Any]],
        exclude_task_ids: Optional[set[str]] = None,
    ) -> set[str]:
        """Task ids that keep a watch with *auth_state* off *to_uri*.

        Connector watches (identified by their auth_state provider) may share a
        target with other Connector watches; anything involving a native watch
        is exclusive.
        """
        others = self._index_get(account_id, to_uri) - (exclude_task_ids or set())
        if not others:
            return set()
        if self._is_connector_auth_state(auth_state) and self._all_connector_tasks(others):
            return set()
        return others

    def _check_uri_conflict(
        self,
        to_uri: Optional[str],
        account_id: str = "default",
        exclude_task_id: Optional[str] = None,
        auth_state: Optional[Dict[str, Any]] = None,
    ) -> bool:
        """Return True when a watch with *auth_state* may not target *to_uri*."""
        exclude = {exclude_task_id} if exclude_task_id else None
        return bool(self._blocking_task_ids(to_uri, account_id, auth_state, exclude))

    async def create_task(
        self,
        path: str,
        account_id: str = "default",
        user_id: str = "default",
        original_role: str = "user",
        source_type: Optional[str] = None,
        to_uri: Optional[str] = None,
        to_is_directory: Optional[bool] = None,
        parent_uri: Optional[str] = None,
        reason: str = "",
        instruction: str = "",
        watch_interval: float = 60.0,
        build_index: bool = True,
        summarize: bool = False,
        processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
        processor_kwargs: Optional[Dict[str, Any]] = None,
        auth_state: Optional[Dict[str, Any]] = None,
        connector_states: Optional[Dict[str, Any]] = None,
        is_active: bool = True,
    ) -> WatchTask:
        """Create and persist a watch task while its target URI is stable."""
        if not path:
            raise ValueError("Path is required")
        if watch_interval <= 0:
            raise ValueError("watch_interval must be > 0")

        async with self._uri_mutation_coordinator.access(account_id, [to_uri]):
            async with self._lock:
                blocking = self._blocking_task_ids(to_uri, account_id, auth_state)
                if blocking:
                    # The target URI is the watch identity; only Connector watches
                    # may share one, and never with a native watch.
                    raise ConflictError(
                        f"Target URI '{to_uri}' is already being monitored by an incompatible watch. "
                        "Delete the conflicting watch or choose another target.",
                        resource=to_uri,
                    )

                task = WatchTask(
                    path=path,
                    source_type=source_type,
                    to_uri=to_uri,
                    to_is_directory=to_is_directory,
                    parent_uri=parent_uri,
                    reason=reason,
                    instruction=instruction,
                    watch_interval=watch_interval,
                    build_index=build_index,
                    summarize=summarize,
                    processing_mode=processing_mode,
                    processor_kwargs=processor_kwargs or {},
                    auth_state=auth_state,
                    connector_states=connector_states,
                    is_active=is_active,
                    account_id=account_id,
                    user_id=user_id,
                    original_role=original_role,
                )

                task.next_execution_time = (
                    task.calculate_next_execution_time() if task.is_active else None
                )

                self._tasks[task.task_id] = task
                self._index_add(account_id, to_uri, task.task_id)

                await self._save_tasks()

                logger.info(
                    f"[WatchManager] Created task {task.task_id} for path {path} "
                    f"by user {account_id}/{user_id}"
                )
                return task

    async def update_task(
        self,
        task_id: str,
        account_id: str,
        user_id: str,
        role: str,
        path: Optional[str] = None,
        source_type: Optional[str] = None,
        to_uri: Optional[str] = None,
        to_is_directory: Optional[bool] = None,
        parent_uri: Optional[str] = None,
        reason: Optional[str] = None,
        instruction: Optional[str] = None,
        watch_interval: Optional[float] = None,
        build_index: Optional[bool] = None,
        summarize: Optional[bool] = None,
        processing_mode: Optional[ProcessingMode] = None,
        processor_kwargs: Optional[Dict[str, Any]] = None,
        auth_state: Any = _UNSET,
        connector_states: Any = _UNSET,
        is_active: Optional[bool] = None,
        invalidate_source_checkpoint: bool = False,
    ) -> WatchTask:
        """Update a watch task while its current and requested target URIs are stable."""
        while True:
            async with self._lock:
                snapshot = self._tasks.get(task_id)
                if not snapshot:
                    raise ValueError(f"Task {task_id} not found")
                stable_account_id = snapshot.account_id
                stable_to_uri = snapshot.to_uri

            async with self._uri_mutation_coordinator.access(
                stable_account_id, [stable_to_uri, to_uri]
            ):
                async with self._lock:
                    task = self._tasks.get(task_id)
                    if not task:
                        raise ValueError(f"Task {task_id} not found")
                    if task.account_id != stable_account_id or task.to_uri != stable_to_uri:
                        continue
                    if not self._check_permission(task, account_id, user_id, role):
                        raise PermissionDeniedError(
                            f"User {account_id}/{user_id} does not have permission to "
                            f"update task {task_id}"
                        )
                    return await self._update_task_unlocked(
                        task,
                        account_id=account_id,
                        user_id=user_id,
                        path=path,
                        source_type=source_type,
                        to_uri=to_uri,
                        to_is_directory=to_is_directory,
                        parent_uri=parent_uri,
                        reason=reason,
                        instruction=instruction,
                        watch_interval=watch_interval,
                        build_index=build_index,
                        summarize=summarize,
                        processing_mode=processing_mode,
                        processor_kwargs=processor_kwargs,
                        auth_state=auth_state,
                        connector_states=connector_states,
                        is_active=is_active,
                        invalidate_source_checkpoint=invalidate_source_checkpoint,
                    )

    async def _update_task_unlocked(
        self,
        task: WatchTask,
        *,
        account_id: str,
        user_id: str,
        path: Optional[str],
        source_type: Optional[str],
        to_uri: Optional[str],
        to_is_directory: Optional[bool],
        parent_uri: Optional[str],
        reason: Optional[str],
        instruction: Optional[str],
        watch_interval: Optional[float],
        build_index: Optional[bool],
        summarize: Optional[bool],
        processing_mode: Optional[ProcessingMode],
        processor_kwargs: Optional[Dict[str, Any]],
        auth_state: Any,
        connector_states: Any,
        is_active: Optional[bool],
        invalidate_source_checkpoint: bool,
    ) -> WatchTask:
        task_id = task.task_id
        if self._check_uri_conflict(
            to_uri,
            account_id=task.account_id,
            exclude_task_id=task_id,
            auth_state=task.auth_state if auth_state is _UNSET else auth_state,
        ):
            raise ConflictError(
                f"Target URI '{to_uri}' is already being monitored by an incompatible watch. "
                "Delete the conflicting watch or choose another target.",
                resource=to_uri,
            )

        old_to_uri = task.to_uri
        if path is not None:
            task.path = path
        if source_type is not None:
            task.source_type = source_type
        if to_uri is not None:
            task.to_uri = to_uri
        if to_is_directory is not None:
            task.to_is_directory = to_is_directory
        if parent_uri is not None:
            task.parent_uri = parent_uri
        if reason is not None:
            task.reason = reason
        if instruction is not None:
            task.instruction = instruction
        if watch_interval is not None:
            if watch_interval <= 0:
                if is_active is True:
                    raise ValueError("watch_interval must be > 0 for active tasks")
                task.watch_interval = watch_interval
                task.is_active = False
                task.next_execution_time = None
            else:
                task.watch_interval = watch_interval
        if build_index is not None:
            task.build_index = build_index
        if summarize is not None:
            task.summarize = summarize
        if processing_mode is not None:
            task.processing_mode = processing_mode
        if processor_kwargs is not None:
            task.processor_kwargs = processor_kwargs
        if auth_state is not _UNSET:
            task.auth_state = auth_state
        if connector_states is not _UNSET:
            if connector_states is not None and not isinstance(connector_states, dict):
                raise ValueError("connector_states must be an object")
            task.connector_states = connector_states
        if is_active is not None:
            task.is_active = is_active
        if invalidate_source_checkpoint:
            task.source_checkpoint = None

        if watch_interval is not None:
            if task.is_active and task.watch_interval > 0:
                task.next_execution_time = task.calculate_next_execution_time()
            else:
                task.next_execution_time = None
        if is_active is not None and watch_interval is None:
            if task.is_active:
                if task.watch_interval <= 0:
                    raise ValueError("watch_interval must be > 0 for active tasks")
                if task.next_execution_time is None:
                    task.next_execution_time = task.calculate_next_execution_time()
            else:
                task.next_execution_time = None

        if to_uri is not None:
            if old_to_uri and old_to_uri != to_uri:
                self._index_remove(task.account_id, old_to_uri, task_id)
            self._index_add(task.account_id, to_uri, task_id)

        await self._save_tasks()
        logger.info(f"[WatchManager] Updated task {task_id} by user {account_id}/{user_id}")
        return task

    async def update_auth_state(
        self,
        task_id: str,
        auth_state: Optional[Dict[str, Any]],
    ) -> None:
        """Update private auth state for an existing watch task."""
        async with self._lock:
            task = self._tasks.get(task_id)
            if not task:
                return
            task.auth_state = auth_state
            await self._save_tasks()

    async def update_connector_states(
        self,
        task_id: str,
        connector_states: Dict[str, Any],
    ) -> None:
        """Update private stream states for an external Connector watch."""
        if not isinstance(connector_states, dict):
            raise ValueError("connector_states must be an object")
        async with self._lock:
            task = self._tasks.get(task_id)
            if not task:
                return
            task.connector_states = connector_states
            await self._save_tasks()

    async def update_source_checkpoint(
        self,
        task_id: str,
        source_checkpoint: Optional[Dict[str, Any]],
    ) -> None:
        """Persist the source version checkpoint recorded after a successful refresh."""
        if source_checkpoint is not None and not isinstance(source_checkpoint, dict):
            raise ValueError("source_checkpoint must be an object")
        async with self._lock:
            task = self._tasks.get(task_id)
            if not task:
                return
            task.source_checkpoint = source_checkpoint
            await self._save_tasks()

    async def record_execution(
        self,
        task_id: str,
        *,
        status: str,
        execution_task_id: Optional[str] = None,
        error: Optional[str] = None,
    ) -> None:
        """Persist the latest execution result exposed by watch APIs."""
        if not status:
            raise ValueError("status is required")
        sanitized_error = (
            sanitize_public_http_error(code="WATCH_EXECUTION_FAILED", message=error).message
            if error
            else None
        )
        async with self._lock:
            task = self._tasks.get(task_id)
            if not task:
                return
            task.last_task_id = execution_task_id
            task.last_status = status
            task.last_error = sanitized_error
            task.last_execution_time = datetime.now()
            task.next_execution_time = (
                task.calculate_next_execution_time()
                if task.is_active and task.watch_interval > 0
                else None
            )
            await self._save_tasks()

    def _plan_target_prefix_rewrite_unlocked(
        self,
        old_uri: str,
        new_uri: str,
        account_id: str = "default",
    ) -> Dict[str, str]:
        old_prefix = old_uri.rstrip("/")
        new_prefix = new_uri.rstrip("/")
        plan: Dict[str, str] = {}
        for task_id, task in self._tasks.items():
            if task.account_id == account_id and _uri_matches_prefix(task.to_uri, old_prefix):
                plan[task_id] = _rewrite_uri_prefix(task.to_uri or "", old_prefix, new_prefix)

        moving_task_ids = set(plan)
        landing: Dict[str, set[str]] = {}
        for task_id, target_uri in plan.items():
            landing.setdefault(target_uri, set()).add(task_id)
        for target_uri, movers in landing.items():
            # Whoever ends up on the target (stayers plus movers) must be able to
            # share it: more than one occupant is only fine when all are Connector.
            occupants = (self._index_get(account_id, target_uri) - moving_task_ids) | movers
            if len(occupants) > 1 and not self._all_connector_tasks(occupants):
                raise ConflictError(
                    f"Target URI '{target_uri}' is already being monitored by an incompatible watch. "
                    "Delete the conflicting watch or choose another target.",
                    resource=target_uri,
                )
        return plan

    async def validate_target_prefix_rewrite_internal(
        self,
        old_uri: str,
        new_uri: str,
        account_id: str = "default",
    ) -> None:
        """Validate a watch target prefix rewrite without changing state."""
        async with self._lock:
            self._plan_target_prefix_rewrite_unlocked(old_uri, new_uri, account_id)

    async def rewrite_target_prefix_internal(
        self,
        old_uri: str,
        new_uri: str,
        account_id: str = "default",
    ) -> List[WatchTask]:
        """Atomically rewrite matching watch target URIs and persist the result."""
        async with self._lock:
            plan = self._plan_target_prefix_rewrite_unlocked(old_uri, new_uri, account_id)
            if not plan:
                return []

            original_targets = {
                task_id: (task.to_uri, task.parent_uri)
                for task_id, task in self._tasks.items()
                if task_id in plan
            }
            original_uri_to_task = {key: set(ids) for key, ids in self._uri_to_task.items()}

            try:
                for task_id in plan:
                    task = self._tasks[task_id]
                    self._index_remove(account_id, task.to_uri, task_id)

                updated: List[WatchTask] = []
                for task_id, target_uri in plan.items():
                    task = self._tasks[task_id]
                    old_parent = _parent_uri(task.to_uri or "")
                    task.to_uri = target_uri
                    if task.parent_uri is not None and task.parent_uri == old_parent:
                        task.parent_uri = _parent_uri(target_uri)
                    self._index_add(account_id, target_uri, task_id)
                    updated.append(task)

                await self._save_tasks()
                logger.info(
                    f"[WatchManager] Rewrote {len(updated)} watch task target URI(s) "
                    f"under {old_uri} to {new_uri}"
                )
                return updated
            except Exception:
                for task_id, (
                    original_to_uri,
                    original_parent_uri,
                ) in original_targets.items():
                    task = self._tasks[task_id]
                    task.to_uri = original_to_uri
                    task.parent_uri = original_parent_uri
                self._uri_to_task = original_uri_to_task
                raise

    async def deactivate_tasks_under_uri_internal(
        self, uri: str, account_id: str = "default"
    ) -> List[WatchTask]:
        """Deactivate watch tasks whose target URI is deleted."""
        async with self._uri_mutation_coordinator.access(account_id, [uri]):
            async with self._lock:
                matched = [
                    task
                    for task in self._tasks.values()
                    if task.account_id == account_id and _uri_matches_prefix(task.to_uri, uri)
                ]
                if not matched:
                    return []

                for task in matched:
                    task.is_active = False
                    task.next_execution_time = None

                await self._save_tasks()
                logger.info(f"[WatchManager] Deactivated {len(matched)} watch task(s) under {uri}")
                return matched

    async def delete_task(
        self,
        task_id: str,
        account_id: str,
        user_id: str,
        role: str,
    ) -> bool:
        """Delete a monitoring task.

        Args:
            task_id: Task ID to delete
            account_id: Requester's account ID
            user_id: Requester's user ID
            role: Requester's role (ROOT/ADMIN/USER)

        Returns:
            True if task was deleted, False if not found

        Raises:
            PermissionDeniedError: If user doesn't have permission
        """
        while True:
            async with self._lock:
                snapshot = self._tasks.get(task_id)
                if not snapshot:
                    return False
                stable_account_id = snapshot.account_id
                stable_to_uri = snapshot.to_uri

            async with self._uri_mutation_coordinator.access(stable_account_id, [stable_to_uri]):
                async with self._lock:
                    task = self._tasks.get(task_id)
                    if not task:
                        return False
                    if task.account_id != stable_account_id or task.to_uri != stable_to_uri:
                        continue
                    if not self._check_permission(task, account_id, user_id, role):
                        raise PermissionDeniedError(
                            f"User {account_id}/{user_id} does not have permission to "
                            f"delete task {task_id}"
                        )

                    self._tasks.pop(task_id, None)
                    self._index_remove(task.account_id, task.to_uri, task_id)

                    try:
                        await self._save_tasks()
                    except Exception:
                        self._tasks[task_id] = task
                        self._index_add(task.account_id, task.to_uri, task_id)
                        raise
                    logger.info(
                        f"[WatchManager] Deleted task {task_id} by user {account_id}/{user_id}"
                    )
                    return True

    async def get_task(
        self,
        task_id: str,
        account_id: str = "default",
        user_id: str = "default",
        role: str = "root",
    ) -> Optional[WatchTask]:
        """Get a monitoring task by ID.

        Args:
            task_id: Task ID to query
            account_id: Requester's account ID
            user_id: Requester's user ID
            role: Requester's role (ROOT/ADMIN/USER)

        Returns:
            WatchTask if found and accessible, None otherwise
        """
        while True:
            async with self._lock:
                snapshot = self._tasks.get(task_id)
                if not snapshot:
                    return None
                stable_account_id = snapshot.account_id
                stable_to_uri = snapshot.to_uri

            async with self._uri_mutation_coordinator.access(stable_account_id, [stable_to_uri]):
                async with self._lock:
                    task = self._tasks.get(task_id)
                    if not task:
                        return None
                    if task.account_id != stable_account_id or task.to_uri != stable_to_uri:
                        continue
                    if not self._check_permission(task, account_id, user_id, role):
                        return None
                    return task

    async def get_all_tasks(
        self,
        account_id: str,
        user_id: str,
        role: str,
        active_only: bool = False,
    ) -> List[WatchTask]:
        """Get all monitoring tasks accessible by the user.

        Args:
            account_id: Requester's account ID
            user_id: Requester's user ID
            role: Requester's role (ROOT/ADMIN/USER)
            active_only: If True, only return active tasks

        Returns:
            List of accessible WatchTask objects
        """
        async with self._lock:
            tasks = []
            for task in self._tasks.values():
                if not self._check_permission(task, account_id, user_id, role):
                    continue
                if active_only and not task.is_active:
                    continue
                tasks.append(task)
            return sorted(tasks, key=lambda task: task.created_at, reverse=True)

    async def get_task_by_uri(
        self,
        to_uri: str,
        account_id: str,
        user_id: str,
        role: str,
    ) -> Optional[WatchTask]:
        """Get a monitoring task by target URI.

        Args:
            to_uri: Target URI to query
            account_id: Requester's account ID
            user_id: Requester's user ID
            role: Requester's role (ROOT/ADMIN/USER)

        Returns:
            WatchTask if found and accessible, None otherwise

        Raises:
            ConflictError: Several accessible Connector watches share *to_uri*;
                address one by task_id instead.
        """
        async with self._uri_mutation_coordinator.access(account_id, [to_uri]):
            async with self._lock:
                task_ids = {
                    task_id
                    for task_id in self._index_get(account_id, to_uri)
                    if (task := self._tasks.get(task_id)) is not None
                    and self._check_permission(task, account_id, user_id, role)
                }
                if not task_ids:
                    return None
                if len(task_ids) > 1:
                    raise ConflictError(
                        f"Target URI '{to_uri}' has {len(task_ids)} watch tasks "
                        f"({', '.join(sorted(task_ids))}); address one by task_id.",
                        resource=to_uri,
                    )

                return self._tasks[next(iter(task_ids))]

    async def update_execution_time(self, task_id: str) -> None:
        """Update task execution time after execution.

        Args:
            task_id: Task ID to update
        """
        async with self._lock:
            task = self._tasks.get(task_id)
            if not task:
                return

            if not task.is_active or task.watch_interval <= 0:
                task.is_active = False
                task.next_execution_time = None
                await self._save_tasks()
                return

            task.last_execution_time = datetime.now()
            task.next_execution_time = task.calculate_next_execution_time()

            await self._save_tasks()

    async def get_due_tasks(self, account_id: Optional[str] = None) -> List[WatchTask]:
        """Get all tasks that are due for execution.

        Args:
            account_id: Optional account ID filter (for scheduler)

        Returns:
            List of tasks that need to be executed
        """
        async with self._lock:
            now = datetime.now()
            due_tasks = []

            for task in self._tasks.values():
                if not task.is_active:
                    continue

                if account_id and task.account_id != account_id:
                    continue

                if task.next_execution_time and task.next_execution_time <= now:
                    due_tasks.append(task)

            return due_tasks

    async def get_next_execution_time(self, account_id: Optional[str] = None) -> Optional[datetime]:
        async with self._lock:
            next_times: List[datetime] = []
            for task in self._tasks.values():
                if not task.is_active:
                    continue
                if account_id and task.account_id != account_id:
                    continue
                if task.next_execution_time is None:
                    continue
                next_times.append(task.next_execution_time)
            return min(next_times) if next_times else None