"""Abstract persistence API for custom skill ownership + publish state."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class SkillStore(ABC):
    @abstractmethod
    async def list_visible(self, user_id: str) -> list[dict[str, Any]]:
        """List all skill records visible to ``user_id``.

        Visible = owner, OR published by anyone, OR built-in (owner_user_id IS NULL).
        """
        raise NotImplementedError

    @abstractmethod
    async def get_visible(self, name: str, user_id: str) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def get_any(self, name: str) -> dict[str, Any] | None:
        """Lookup by name regardless of ownership/visibility (admin / cascade use)."""
        raise NotImplementedError

    @abstractmethod
    async def get_owned(self, name: str, user_id: str) -> dict[str, Any] | None:
        raise NotImplementedError

    @abstractmethod
    async def create(self, data: dict[str, Any]) -> dict[str, Any]:
        """Create a skill record. Caller is responsible for global-name uniqueness check."""
        raise NotImplementedError

    @abstractmethod
    async def ensure_legacy(self, data: dict[str, Any]) -> dict[str, Any]:
        """Idempotently insert a legacy on-disk skill into the DB. Updates the row if it
        already exists with ``owner_user_id IS NULL`` (so a re-run can migrate ownership).
        """
        raise NotImplementedError

    @abstractmethod
    async def update(self, name: str, user_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
        """Owner-only update. Returns None if the caller doesn't own the skill."""
        raise NotImplementedError

    @abstractmethod
    async def update_admin(self, name: str, data: dict[str, Any]) -> dict[str, Any] | None:
        """Admin override — caller is responsible for auth check.

        Unlike ``update_builtin`` for agents, this accepts ANY skill including
        user-owned ones, since the spec lets admin take down others' skills.
        """
        raise NotImplementedError

    @abstractmethod
    async def delete(self, name: str, user_id: str) -> bool:
        raise NotImplementedError

    @abstractmethod
    async def delete_admin(self, name: str) -> bool:
        """Admin-side delete; bypasses ownership check (caller authorizes)."""
        raise NotImplementedError

    @abstractmethod
    async def count_owned(self, user_id: str) -> int:
        """Return the number of skills owned by ``user_id`` (owner_user_id IS NOT NULL)."""
        raise NotImplementedError

    @abstractmethod
    async def list_all(self) -> list[dict[str, Any]]:
        """Return every skill record regardless of ownership/visibility.

        Caller is responsible for authorization (admin only).
        """
        raise NotImplementedError

    @abstractmethod
    async def list_published_names(self) -> set[str]:
        """Return the set of skill names with ``published = True`` (any owner).

        Batch alternative to calling ``get_any`` per skill — the curator uses
        this to filter out published skills in a single query instead of one
        DB round-trip per candidate skill.
        """
        raise NotImplementedError

    @abstractmethod
    async def list_always_on_names(self) -> set[str]:
        """Return the set of skill names marked 常驻(免压缩) (``always_on = True``).

        Batch query used by the prompt builder to decide which skills bypass
        skill compression — one query instead of a per-skill round-trip.
        """
        raise NotImplementedError

    @abstractmethod
    async def list_favorite_skill_names(self, user_id: str) -> set[str]:
        """Return the skill names in ``user_id``'s "我的技能" collection.

        These are skills the user does not own but that landed in their list —
        currently only via their 岗位 (position) sync (``origin='position'``).
        Owned skills are NOT included here (the caller detects those via
        ``owner_user_id``).
        """
        raise NotImplementedError