"""Abstract task-workspace button persistence API.

Global / shared store: no ``user_id`` scoping. Reads are open to any caller; the
router gates writes behind admin. ``updated_by`` is audit-only.

The whole button set is treated as one document: the editor computes the full
desired layout and replaces every row atomically via :meth:`replace_all`, so the
stored set never drifts out of sync with what the admin sees.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class TaskButtonStore(ABC):
    @abstractmethod
    async def list_buttons(self) -> list[dict[str, Any]]:
        """Return every stored button row (order unspecified)."""
        raise NotImplementedError

    @abstractmethod
    async def replace_all(self, rows: list[dict[str, Any]], *, updated_by: str | None = None) -> list[dict[str, Any]]:
        """Atomically replace the entire button set with ``rows``.

        Each row is ``{id, business, label, link_type, target, append_task_id,
        enabled, sort_order}``. Returns the persisted rows.
        """
        raise NotImplementedError