Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

70.9 KB
Raw Blame
"""
PocketBase-backed session store.

Implements SessionStoreProtocol using PocketBase collections for all durable
storage.  The key performance design:

- Most methods make direct PocketBase HTTP calls. These are called at most a
  handful of times per turn (create, get, update status, add message) and the
  ~5–10 ms overhead is acceptable.

- Turn events are flushed before a terminal status is committed.  This makes
  the PocketBase and SQLite backends share one durability contract: DONE never
  races a detached upload task and shutdown cannot silently lose trace rows.
"""

from __future__ import annotations

import asyncio
import contextlib
from datetime import datetime
from functools import wraps
import json
import logging
import re
import time
from typing import Any
import uuid

from deeptutor.services.session.protocol import ActiveTurnConflict
from deeptutor.services.workspace.context import current_workspace_id

from .ask_user_trace import filter_ask_user_events
from .event_preview import MAX_TRACE_PREVIEW_EVENTS, compact_trace_preview
from .provider_response_state import redact_private_message_metadata
from .scope import StoreScope
from .search import bounded_search_excerpt, normalize_search_query
from .workspace_preferences import upgrade_workspace_preferences

logger = logging.getLogger(__name__)

_VALID_ID = re.compile(r"^[a-zA-Z0-9_-]+$")
_ACTIVE_TURN_STATUSES = frozenset({"queued", "running", "waiting_input"})
_TERMINAL_TURN_STATUSES = frozenset({"completed", "failed", "cancelled"})
_ALL_TURN_STATUSES = _ACTIVE_TURN_STATUSES | _TERMINAL_TURN_STATUSES
# The deployed PocketBase messages collection has no parent column. Keep the
# link inside its JSON metadata until the collection schema can be upgraded.
_PARENT_MESSAGE_METADATA_KEY = "_parent_message_id"
_SUMMARY_CURSOR_PREFERENCE_KEY = "_summary_message_id"


def _captured_store_context(method):
    """Provider-created stores cannot be redirected by a later ambient scope."""

    @wraps(method)
    async def call(self, *args, **kwargs):
        if self.store_scope is None:
            return await method(self, *args, **kwargs)
        from deeptutor.multi_user.context import get_current_user
        from deeptutor.services.workspace.context import workspace_context

        if get_current_user().id != self.store_scope.owner_id:
            raise ValueError("Session store belongs to another account.")
        with workspace_context(self._workspace_scope):
            return await method(self, *args, **kwargs)

    return call


def _validate_id(value: str, name: str = "id") -> str:
    if not _VALID_ID.match(value):
        raise ValueError(f"Invalid {name}: {value!r}")
    return value


def _json_loads(value: Any, default: Any) -> Any:
    if not value:
        return default
    if isinstance(value, (dict, list)):
        return value
    try:
        return json.loads(value)
    except Exception:
        return default


def _pb():
    """Return the shared PocketBase client."""
    from deeptutor.services.pocketbase_client import get_pb_client

    return get_pb_client()


def _to_float(value: Any, default: float = 0.0) -> float:
    try:
        return float(value) if value is not None else default
    except (TypeError, ValueError):
        if isinstance(value, str):
            try:
                return datetime.fromisoformat(value.replace("Z", "+00:00")).timestamp()
            except ValueError:
                pass
        return default


def _current_user_id() -> str:
    """Id of the request-scoped current user, used to isolate session rows.

    PocketBase is a single shared server queried by one process-wide
    admin-authenticated client, so it has no filesystem-level isolation. Every
    session row is therefore scoped by ``user_id`` (the SQLite backend isolates
    via a per-user database file instead — see ``get_sqlite_session_store``).
    This reads the same ``_current_user`` ContextVar that the SQLite path
    service resolves against, so the two backends share one source of truth and
    are equally reliable across HTTP, WebSocket, and turn-runtime threads. Falls
    back to the local-admin id in single-user / no-auth mode.

    The id is validated (it always matches ``_VALID_ID`` for real users — a
    PocketBase record id, a ``u_<hex>`` id, or ``local-admin``) so it is safe to
    interpolate into a PocketBase filter string.
    """
    from deeptutor.multi_user.context import get_current_user

    return _validate_id(get_current_user().id, "user_id")


def _find_session_record(
    pb: Any, session_id: str, user_id: str, *, recycled: bool | None = None
) -> Any | None:
    """Return the ``sessions`` record for *session_id* owned by *user_id*.

    Scoping every session lookup by ``user_id`` is the single point that keeps
    one user from reading or mutating another's sessions on the shared
    PocketBase backend. Returns ``None`` when no such row exists for this user.

    ``recycled`` narrows the match by ``deleted_at`` — ``False`` requires an
    active session, ``True`` requires one already in the recycle bin, and
    ``None`` (the default) ignores the recycle-bin state entirely, preserving
    lookup behaviour for callers that predate it. One column carries this:
    a row is in the bin exactly when ``deleted_at`` is set.
    """
    records = pb.collection("sessions").get_full_list(
        query_params={
            "filter": _workspace_filter(f'session_id="{session_id}" && user_id="{user_id}"')
        }
    )
    if not records:
        return None
    record = records[0]
    if not _in_workspace(record):
        return None
    if recycled is not None and bool(_to_float(getattr(record, "deleted_at", None))) != recycled:
        return None
    return record


def _workspace_filter(expression: str) -> str:
    workspace_id = current_workspace_id()
    field = "preferences_json.workspace_id"
    partition = (
        f"{field}={json.dumps(workspace_id)}" if workspace_id else f'({field}=null || {field}="")'
    )
    return f"({expression}) && {partition}"


def _in_workspace(record) -> bool:
    prefs = _json_loads(getattr(record, "preferences_json", None), {})
    return str(prefs.get("workspace_id") or "") == current_workspace_id()


class PocketBaseSessionStore:
    """PocketBase-backed implementation of SessionStoreProtocol."""

    def __init__(self) -> None:
        self._closed = False
        self.store_scope: StoreScope | None = None
        from deeptutor.services.workspace.context import get_workspace_scope

        self._workspace_scope = get_workspace_scope()

    @_captured_store_context
    async def close(self) -> None:
        """Prevent lifecycle owners from retaining an already-closed store."""
        self._closed = True

    # ------------------------------------------------------------------
    # Sessions
    # ------------------------------------------------------------------

    @_captured_store_context
    async def migrate_workspace_preferences(self) -> int:
        """Persist canonical workspace metadata for the current PocketBase user.

        The explicit logical timestamps keep this metadata-only migration from
        changing conversation order even though PocketBase updates its own
        system ``updated`` field whenever a record is written.
        """

        uid = _current_user_id()

        def _migrate() -> int:
            collection = _pb().collection("sessions")
            records = collection.get_full_list(query_params={"filter": f'user_id="{uid}"'})
            records.sort(
                key=lambda record: (
                    _to_float(getattr(record, "session_updated_at", None))
                    or _to_float(getattr(record, "updated", None))
                )
            )
            migrated = 0
            for record in records:
                current = _json_loads(getattr(record, "preferences_json", None), {})
                upgraded = upgrade_workspace_preferences(current)
                created_at = (
                    _to_float(getattr(record, "session_created_at", None))
                    or _to_float(getattr(record, "created", None))
                    or time.time()
                )
                updated_at = (
                    _to_float(getattr(record, "session_updated_at", None))
                    or _to_float(getattr(record, "updated", None))
                    or created_at
                )
                payload: dict[str, Any] = {}
                if _to_float(getattr(record, "deleted_at", None)):
                    upgraded = {**upgraded, "archived": True}
                    payload["deleted_at"] = None
                    payload["preferences_json"] = upgraded
                if upgraded != current:
                    payload["preferences_json"] = upgraded
                    migrated += 1
                if not _to_float(getattr(record, "session_created_at", None)):
                    payload["session_created_at"] = created_at
                if not _to_float(getattr(record, "session_updated_at", None)):
                    payload["session_updated_at"] = updated_at
                if payload:
                    collection.update(record.id, payload)
            return migrated

        return await asyncio.to_thread(_migrate)

    @_captured_store_context
    async def create_session(
        self,
        title: str | None = None,
        session_id: str | None = None,
    ) -> dict[str, Any]:
        now = time.time()
        resolved_id = session_id or f"unified_{int(now * 1000)}_{uuid.uuid4().hex[:8]}"
        resolved_title = (title or "New conversation").strip() or "New conversation"
        owner_id = _current_user_id()

        def _create():
            return (
                _pb()
                .collection("sessions")
                .create(
                    {
                        "session_id": resolved_id,
                        "user_id": owner_id,
                        "title": resolved_title[:100],
                        "compressed_summary": "",
                        "summary_up_to_msg_id": 0,
                        "preferences_json": {"workspace_id": current_workspace_id()},
                        "capability": "",
                        "status": "idle",
                        "session_created_at": now,
                        "session_updated_at": now,
                    }
                )
            )

        record = await asyncio.to_thread(_create)
        return self._session_record_to_dict(record, resolved_id, resolved_title, now)

    @_captured_store_context
    async def get_session(self, session_id: str) -> dict[str, Any] | None:
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _get():
            try:
                return _find_session_record(_pb(), sid, uid, recycled=False)
            except Exception:
                return None

        record = await asyncio.to_thread(_get)
        if record is None:
            return None
        return self._session_record_to_dict(record)

    @_captured_store_context
    async def ensure_session(
        self,
        session_id: str | None = None,
    ) -> dict[str, Any]:
        if session_id:
            session = await self.get_session(session_id)
            if session is not None:
                return session
        return await self.create_session()

    def _session_record_to_dict(
        self,
        record: Any,
        session_id: str | None = None,
        title: str | None = None,
        now: float | None = None,
    ) -> dict[str, Any]:
        sid = session_id or getattr(record, "session_id", getattr(record, "id", ""))
        t = title or getattr(record, "title", "New conversation") or "New conversation"
        created = (
            _to_float(getattr(record, "session_created_at", None))
            or _to_float(getattr(record, "created", None))
            or now
            or time.time()
        )
        updated = (
            _to_float(getattr(record, "session_updated_at", None))
            or _to_float(getattr(record, "updated", None))
            or now
            or time.time()
        )
        preferences_raw = getattr(record, "preferences_json", None)
        preferences = _json_loads(preferences_raw, {})
        preferences = dict(preferences) if isinstance(preferences, dict) else {}
        summary_cursor = preferences.pop(_SUMMARY_CURSOR_PREFERENCE_KEY, None)
        deleted_at_raw = getattr(record, "deleted_at", None)
        return {
            "id": sid,
            "session_id": sid,
            "title": t,
            "created_at": created,
            "updated_at": updated,
            "compressed_summary": getattr(record, "compressed_summary", "") or "",
            "summary_up_to_msg_id": summary_cursor
            or int(getattr(record, "summary_up_to_msg_id", 0) or 0),
            # PocketBase has no local schema-upgrade hook. Normalize at the
            # repository boundary so old remote rows immediately satisfy the
            # same API contract; their next preference write persists it.
            "preferences": upgrade_workspace_preferences(preferences),
            "capability": getattr(record, "capability", "") or "",
            "status": getattr(record, "status", "idle") or "idle",
            "active_turn_id": "",
            "is_deleted": bool(_to_float(getattr(record, "deleted_at", None))),
            "deleted_at": _to_float(deleted_at_raw) if deleted_at_raw not in (None, "") else None,
        }

    @_captured_store_context
    async def update_session_title(self, session_id: str, title: str) -> bool:
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _update():
            record = _find_session_record(_pb(), sid, uid)
            if record is None:
                return False
            _pb().collection("sessions").update(
                record.id,
                {
                    "title": (title.strip() or "New conversation")[:100],
                    "session_updated_at": time.time(),
                },
            )
            return True

        try:
            return await asyncio.to_thread(_update)
        except Exception as exc:
            logger.warning(f"update_session_title failed: {exc}")
            return False

    @_captured_store_context
    async def import_legacy_session(
        self,
        session_id: str,
        title: str,
        created_at: float,
        updated_at: float,
        preferences: dict[str, Any],
        messages: list[dict[str, Any]],
    ) -> dict[str, Any]:
        """Atomically-as-possible import one v1 chat into PocketBase.

        PocketBase has no cross-collection transaction in the Python client,
        so a failed import explicitly removes every row it created before the
        error is re-raised. Existing sessions are never updated.
        """

        sid = _validate_id(session_id, "session_id")
        owner_id = _current_user_id()

        def _import() -> dict[str, Any]:
            if _find_session_record(_pb(), sid, owner_id) is not None:
                return {"session_id": sid, "imported": False, "message_count": 0}
            session_record = None
            created_message_ids: list[str] = []
            try:
                session_record = (
                    _pb()
                    .collection("sessions")
                    .create(
                        {
                            "session_id": sid,
                            "user_id": owner_id,
                            "title": (title or "New conversation")[:100],
                            "compressed_summary": "",
                            "summary_up_to_msg_id": 0,
                            "preferences_json": {
                                **(preferences or {}),
                                "workspace_id": current_workspace_id(),
                            },
                            "capability": "chat",
                            "status": "idle",
                            "session_created_at": float(created_at),
                            "session_updated_at": float(updated_at),
                        }
                    )
                )
                for message in messages:
                    record = (
                        _pb()
                        .collection("messages")
                        .create(
                            {
                                "session_id": sid,
                                "role": str(message.get("role") or "user"),
                                "content": str(message.get("content") or ""),
                                "capability": "chat",
                                "events_json": [],
                                "attachments_json": [],
                                "metadata_json": message.get("metadata") or {},
                                "msg_created_at": float(message.get("created_at") or created_at),
                            }
                        )
                    )
                    created_message_ids.append(str(record.id))
            except Exception:
                for message_id in reversed(created_message_ids):
                    with contextlib.suppress(Exception):
                        _pb().collection("messages").delete(message_id)
                if session_record is not None:
                    with contextlib.suppress(Exception):
                        _pb().collection("sessions").delete(str(session_record.id))
                raise
            return {
                "session_id": sid,
                "imported": True,
                "message_count": len(created_message_ids),
            }

        return await asyncio.to_thread(_import)

    @_captured_store_context
    async def delete_session(self, session_id: str) -> bool:
        """Permanently remove a conversation and its stored messages."""
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _do():
            record = _find_session_record(_pb(), sid, uid)
            if record is None:
                return False
            # These collections use logical session IDs, not cascading relations.
            for name in ("turn_events", "turns", "messages"):
                collection = _pb().collection(name)
                for child in collection.get_full_list(
                    query_params={"filter": f'session_id="{sid}"'}
                ):
                    collection.delete(child.id)
            _pb().collection("sessions").delete(record.id)
            return True

        try:
            return await asyncio.to_thread(_do)
        except Exception as exc:
            logger.warning(f"delete_session failed: {exc}")
            return False

    @_captured_store_context
    async def soft_delete_session(self, session_id: str) -> bool:
        """Move a session to the recycle bin (soft delete)."""
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _do():
            record = _find_session_record(_pb(), sid, uid, recycled=False)
            if record is None:
                return False
            _pb().collection("sessions").update(record.id, {"deleted_at": time.time()})
            return True

        try:
            return await asyncio.to_thread(_do)
        except Exception as exc:
            logger.warning(f"soft_delete_session failed: {exc}")
            return False

    @_captured_store_context
    async def restore_session(self, session_id: str) -> bool:
        """Restore a soft-deleted session from the recycle bin."""
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _do():
            record = _find_session_record(_pb(), sid, uid, recycled=True)
            if record is None:
                return False
            _pb().collection("sessions").update(record.id, {"deleted_at": None})
            return True

        try:
            return await asyncio.to_thread(_do)
        except Exception as exc:
            logger.warning(f"restore_session failed: {exc}")
            return False

    @_captured_store_context
    async def hard_delete_session(self, session_id: str) -> bool:
        """Permanently delete a session from the recycle bin.

        Requires a prior soft-delete (defence-in-depth), matching the SQLite
        backend's guard against accidentally skipping the recycle bin.
        """
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _do():
            record = _find_session_record(_pb(), sid, uid, recycled=True)
            if record is None:
                return False
            _pb().collection("sessions").delete(record.id)
            return True

        try:
            return await asyncio.to_thread(_do)
        except Exception as exc:
            logger.warning(f"hard_delete_session failed: {exc}")
            return False

    @_captured_store_context
    async def list_deleted_sessions(self, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
        """List soft-deleted sessions ordered by deletion time.

        PocketBase filter strings can't be trusted across server versions for
        boolean comparisons, so the soft-delete filter and the ``deleted_at``
        ordering are both applied client-side after fetching the user's rows.
        """
        uid = _current_user_id()

        def _do():
            records = (
                _pb()
                .collection("sessions")
                .get_full_list(query_params={"filter": _workspace_filter(f'user_id="{uid}"')})
            )
            deleted = [
                r for r in records if _in_workspace(r) and _to_float(getattr(r, "deleted_at", None))
            ]
            deleted.sort(key=lambda r: _to_float(getattr(r, "deleted_at", None)), reverse=True)
            page = deleted[offset : offset + limit]
            return [self._session_record_to_dict(r) for r in page]

        try:
            return await asyncio.to_thread(_do)
        except Exception as exc:
            logger.warning(f"list_deleted_sessions failed: {exc}")
            return []

    @_captured_store_context
    async def list_sessions(
        self,
        limit: int = 50,
        offset: int = 0,
        *,
        workspace_id: str | None = None,
    ) -> list[dict[str, Any]]:
        limit = max(1, int(limit))
        offset = max(0, int(offset))
        page = (offset // limit) + 1
        skip = offset % limit
        uid = _current_user_id()

        def _list():
            query_params: dict[str, Any] = {
                "sort": "-session_updated_at,session_id",
                "filter": _workspace_filter(f'user_id="{uid}" && deleted_at = null'),
            }
            if workspace_id is not None:
                field = "preferences_json.workspace_id"
                scope = (
                    f"{field}={json.dumps(workspace_id)}"
                    if workspace_id
                    else f'({field}=null || {field}="")'
                )
                query_params["filter"] += (
                    f" && {scope}"
                    " && (preferences_json.archived=null || preferences_json.archived=false)"
                    ' && (preferences_json.parent_session_id=null || preferences_json.parent_session_id="")'
                )
            collection = _pb().collection("sessions")
            result = collection.get_list(page, limit, query_params=query_params)
            records = list(result.items)
            if skip and len(records) == limit:
                records.extend(
                    collection.get_list(page + 1, limit, query_params=query_params).items
                )
            return records[skip : skip + limit]

        try:
            result = await asyncio.to_thread(_list)
            # Reading conversations are listed like any other: the sidebar
            # groups them under their collection and a click returns to the
            # reader. See the note on ``_WHERE_NATIVE`` in the SQLite store.
            #
            # The filter above excludes soft-deleted rows on real PocketBase
            # servers; this is a defensive re-check for servers/mocks where
            # boolean filter comparisons behave unexpectedly.
            return [
                self._session_record_to_dict(r)
                for r in result
                if not _to_float(getattr(r, "deleted_at", None)) and _in_workspace(r)
            ]
        except Exception as exc:
            logger.warning(f"list_sessions failed: {exc}")
            return []

    @_captured_store_context
    async def search_sessions(
        self,
        query: str,
        limit: int = 50,
        offset: int = 0,
    ) -> dict[str, Any]:
        """Search the current user's native sessions without loading transcripts."""
        normalized = normalize_search_query(query)
        if not normalized:
            return {"sessions": [], "total": 0}
        uid = _current_user_id()
        bounded_limit = max(1, min(int(limit), 100))
        bounded_offset = max(0, int(offset))

        def _search() -> dict[str, Any]:
            pb = _pb()
            records = pb.collection("sessions").get_full_list(
                query_params={
                    "filter": _workspace_filter(f"user_id={json.dumps(uid)} && deleted_at = null")
                }
            )
            records = [
                record
                for record in records
                if _in_workspace(record)
                and not _to_float(getattr(record, "deleted_at", None))
                and not str(getattr(record, "session_id", "") or "").startswith("imported_")
            ]
            records.sort(
                key=lambda record: (
                    -(
                        _to_float(getattr(record, "session_updated_at", None))
                        or _to_float(getattr(record, "updated", None))
                    ),
                    str(getattr(record, "session_id", "")),
                ),
            )

            matched: list[tuple[Any, Any | None]] = []
            query_literal = json.dumps(normalized, ensure_ascii=False)
            for record in records:
                sid = _validate_id(str(getattr(record, "session_id", "")), "session_id")
                message_page = pb.collection("messages").get_list(
                    1,
                    1,
                    query_params={
                        "filter": (
                            f"session_id={json.dumps(sid)} && "
                            '(role="user" || role="assistant") && '
                            f"content~{query_literal}"
                        ),
                        "sort": "-msg_created_at,-created",
                    },
                )
                matching_messages = self._page_items(message_page)
                title = str(getattr(record, "title", "") or "")
                if normalized.casefold() in title.casefold() or matching_messages:
                    matched.append((record, matching_messages[0] if matching_messages else None))

            page = matched[bounded_offset : bounded_offset + bounded_limit]
            sessions: list[dict[str, Any]] = []
            for record, match in page:
                session = self._session_record_to_dict(record)
                sid = session["session_id"]
                summary_page = pb.collection("messages").get_list(
                    1,
                    1,
                    query_params={
                        "filter": f'session_id={json.dumps(sid)} && role!="system"',
                        "sort": "-msg_created_at,-created",
                    },
                )
                summary_items = self._page_items(summary_page)
                session["message_count"] = self._page_total(summary_page)
                session["last_message"] = str(
                    getattr(summary_items[0], "content", "") if summary_items else ""
                )
                session["match_message_id"] = getattr(match, "id", None)
                session["match_role"] = getattr(match, "role", None)
                session["match_created_at"] = (
                    _to_float(getattr(match, "msg_created_at", None)) if match is not None else None
                )
                match_content = (
                    str(getattr(match, "content", "") or "")
                    if match is not None
                    else session["title"]
                )
                session["match_excerpt"] = bounded_search_excerpt(match_content, normalized)
                sessions.append(session)
            return {"sessions": sessions, "total": len(matched)}

        try:
            return await asyncio.to_thread(_search)
        except Exception as exc:
            logger.warning(f"search_sessions failed: {exc}")
            return {"sessions": [], "total": 0}

    @_captured_store_context
    async def get_session_summaries(
        self,
        session_ids: list[str],
    ) -> list[dict[str, Any]]:
        """Return bounded metadata without loading complete chat transcripts."""

        async def summarize(session_id: str) -> dict[str, Any] | None:
            session = await self.get_session(session_id)
            if session is None:
                return None
            message_summary, active_turn = await asyncio.gather(
                self._get_message_summary(session_id),
                self.get_active_turn(session_id),
            )
            session.update(message_summary)
            if active_turn is not None:
                session["status"] = active_turn.get("status") or "running"
                session["active_turn_id"] = active_turn.get("id") or ""
            return session

        summaries = await asyncio.gather(
            *(summarize(session_id) for session_id in dict.fromkeys(session_ids))
        )
        return [summary for summary in summaries if summary is not None]

    @_captured_store_context
    async def _get_message_summary(self, session_id: str) -> dict[str, Any]:
        """Fetch one preview row plus PocketBase's aggregate count."""

        sid = _validate_id(session_id, "session_id")

        def _get() -> dict[str, Any]:
            result = (
                _pb()
                .collection("messages")
                .get_list(
                    1,
                    1,
                    query_params={
                        "filter": f'session_id="{sid}" && role!="system"',
                        "sort": "-msg_created_at,-created",
                    },
                )
            )
            total = getattr(result, "total_items", getattr(result, "totalItems", None))
            items = list(getattr(result, "items", ()) or ())
            preview = self._message_record_to_dict(items[0]) if items else None
            return {
                "message_count": max(0, int(total if total is not None else len(items))),
                "last_message": str((preview or {}).get("content") or ""),
            }

        try:
            return await asyncio.to_thread(_get)
        except Exception as exc:
            logger.warning(f"get message summary failed: {exc}")
            return {"message_count": 0, "last_message": ""}

    @_captured_store_context
    async def update_summary(self, session_id: str, summary: str, up_to_msg_id: int | str) -> bool:
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()

        def _update():
            record = _find_session_record(_pb(), sid, uid)
            if record is None:
                return False
            preferences = _json_loads(getattr(record, "preferences_json", None), {})
            preferences = dict(preferences) if isinstance(preferences, dict) else {}
            # The existing server field is numeric. Keep native record IDs in
            # its JSON preferences field, hidden at the repository boundary.
            if isinstance(up_to_msg_id, str):
                preferences[_SUMMARY_CURSOR_PREFERENCE_KEY] = up_to_msg_id
            else:
                preferences.pop(_SUMMARY_CURSOR_PREFERENCE_KEY, None)
            _pb().collection("sessions").update(
                record.id,
                {
                    "compressed_summary": summary,
                    "summary_up_to_msg_id": 0
                    if isinstance(up_to_msg_id, str)
                    else max(0, up_to_msg_id),
                    "preferences_json": preferences,
                },
            )
            return True

        try:
            return await asyncio.to_thread(_update)
        except Exception as exc:
            logger.warning(f"update_summary failed: {exc}")
            return False

    @_captured_store_context
    async def update_session_preferences(
        self, session_id: str, preferences: dict[str, Any], *, touch: bool = True
    ) -> bool:
        sid = _validate_id(session_id, "session_id")

        async def _merge():
            session = await self.get_session(sid)
            if session is None:
                return False
            merged = upgrade_workspace_preferences(
                {**session.get("preferences", {}), **(preferences or {})}
            )
            uid = _current_user_id()

            def _update():
                record = _find_session_record(_pb(), sid, uid)
                if record is None:
                    return False
                current = _json_loads(getattr(record, "preferences_json", None), {})
                if isinstance(current, dict) and _SUMMARY_CURSOR_PREFERENCE_KEY in current:
                    merged[_SUMMARY_CURSOR_PREFERENCE_KEY] = current[_SUMMARY_CURSOR_PREFERENCE_KEY]
                _pb().collection("sessions").update(
                    record.id,
                    {"preferences_json": merged, "session_updated_at": time.time()}
                    if touch
                    else {"preferences_json": merged},
                )
                return True

            return await asyncio.to_thread(_update)

        try:
            return await _merge()
        except Exception as exc:
            logger.warning(f"update_session_preferences failed: {exc}")
            return False

    @_captured_store_context
    async def get_session_with_messages(self, session_id: str) -> dict[str, Any] | None:
        session = await self.get_session(session_id)
        if session is None:
            return None
        session["messages"] = await self.get_messages(session_id)
        redact_private_message_metadata(session["messages"])
        session["active_turns"] = await self.list_active_turns(session_id)
        return session

    # ------------------------------------------------------------------
    # Messages
    # ------------------------------------------------------------------
    # Messages/turns/turn_events are keyed by ``session_id`` and are reached
    # from the API only through a session lookup that is already user-scoped
    # (``get_session_with_messages`` returns ``None`` for another user's
    # session before any message is fetched, and ``create_turn`` rejects a
    # session the caller doesn't own). Internal callers always operate on the
    # current user's own session, so these rows don't carry a separate
    # ``user_id`` filter — the session boundary above is the access gate.

    @_captured_store_context
    async def add_message(
        self,
        session_id: str,
        role: str,
        content: str,
        capability: str = "",
        events: list[dict[str, Any]] | None = None,
        attachments: list[dict[str, Any]] | None = None,
        metadata: dict[str, Any] | None = None,
        parent_message_id: int | str | None = None,
    ) -> int | str:
        sid = _validate_id(session_id, "session_id")
        now = time.time()
        stored_metadata = dict(metadata or {})
        if parent_message_id is not None:
            stored_metadata[_PARENT_MESSAGE_METADATA_KEY] = str(parent_message_id)

        def _add():
            if _find_session_record(_pb(), sid, _current_user_id()) is None:
                raise ValueError("Session not found in this workspace")
            payload = {
                "session_id": sid,
                "role": role,
                "content": content or "",
                "capability": capability or "",
                "events_json": events or [],
                "attachments_json": attachments or [],
                "metadata_json": stored_metadata,
                "msg_created_at": now,
            }
            record = _pb().collection("messages").create(payload)
            uid = _current_user_id()
            session_record = _find_session_record(_pb(), sid, uid)
            if session_record is not None:
                _pb().collection("sessions").update(session_record.id, {"session_updated_at": now})
            # Title generation is owned by the turn runtime (LLM-driven
            # after the first user+assistant pair). Until that runs the
            # session keeps the ``New conversation`` sentinel.
            return record

        try:
            record = await asyncio.to_thread(_add)
            # Return the real PocketBase record id — the same id
            # ``get_messages`` serves — so callers (e.g. the DONE-event
            # reconcile metadata) hand the frontend ids that match what a
            # later session fetch would return.
            return str(getattr(record, "id", "") or "")
        except Exception as exc:
            logger.warning(f"add_message failed: {exc}")
            return 0

    @_captured_store_context
    async def delete_message(self, message_id: int | str) -> bool:
        def _delete():
            row = _pb().collection("messages").get_one(_validate_id(str(message_id)))
            if _find_session_record(_pb(), str(row.session_id), _current_user_id()) is None:
                return False
            _pb().collection("messages").delete(str(message_id))
            return True

        try:
            return await asyncio.to_thread(_delete)
        except Exception as exc:
            logger.warning(f"delete_message failed: {exc}")
            return False

    @_captured_store_context
    async def get_last_message(
        self, session_id: str, role: str | None = None
    ) -> dict[str, Any] | None:
        if await self.get_session(session_id) is None:
            return None
        sid = _validate_id(session_id, "session_id")
        filter_str = f'session_id="{sid}"'
        if role:
            filter_str += f' && role="{role}"'

        def _get():
            records = (
                _pb()
                .collection("messages")
                .get_full_list(
                    query_params={
                        "filter": filter_str,
                        "sort": "-msg_created_at",
                        "perPage": 1,
                    }
                )
            )
            return records[0] if records else None

        try:
            record = await asyncio.to_thread(_get)
            return self._message_record_to_dict(record) if record is not None else None
        except Exception as exc:
            logger.warning(f"get_last_message failed: {exc}")
            return None

    @staticmethod
    def _event_record_to_payload(row: Any, session_id: str, turn_id: str) -> dict[str, Any]:
        return {
            "type": getattr(row, "type", ""),
            "source": getattr(row, "source", "") or "",
            "stage": getattr(row, "stage", "") or "",
            "content": getattr(row, "content", "") or "",
            "metadata": _json_loads(getattr(row, "metadata_json", None), {}),
            "session_id": session_id,
            "turn_id": turn_id,
            "seq": int(getattr(row, "seq", 0) or 0),
            "timestamp": _to_float(getattr(row, "event_timestamp", None)),
        }

    @staticmethod
    def _page_items(page: Any) -> list[Any]:
        return list(getattr(page, "items", ()) or ())

    @staticmethod
    def _page_total(page: Any) -> int:
        value = getattr(page, "total_items", getattr(page, "totalItems", None))
        return max(
            0, int(value if value is not None else len(PocketBaseSessionStore._page_items(page)))
        )

    def _trace_preview(
        self, pb: Any, *, session_id: str, turn_id: str
    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
        turn_id = _validate_id(turn_id, "turn_id")
        page = pb.collection("turn_events").get_list(
            1,
            MAX_TRACE_PREVIEW_EVENTS,
            query_params={"filter": f'turn_id="{turn_id}"', "sort": "-seq"},
        )
        rows = list(reversed(self._page_items(page)))
        events = [self._event_record_to_payload(row, session_id, turn_id) for row in rows]
        preview, omitted = compact_trace_preview(events)
        total = self._page_total(page)
        last_seq = int(getattr(rows[-1], "seq", 0) or 0) if rows else 0
        # The preview is the *tail* of the stream, so its first row is not
        # where the turn began. One extra single-row read gets the real start,
        # without which a turn that thought for a while and then answered in
        # one burst reports a span of zero. See ``_trace_bounds`` in the
        # SQLite store for the same reasoning.
        started_at = ended_at = None
        if rows:
            ended_at = _to_float(getattr(rows[-1], "event_timestamp", None))
            head = self._page_items(
                pb.collection("turn_events").get_list(
                    1,
                    1,
                    query_params={"filter": f'turn_id="{turn_id}"', "sort": "seq"},
                )
            )
            if head:
                started_at = _to_float(getattr(head[0], "event_timestamp", None))
        bounds = (
            {"started_at": started_at, "ended_at": max(started_at, ended_at or started_at)}
            if started_at is not None and ended_at is not None
            else {}
        )
        return preview, {
            "turn_id": turn_id,
            "total": total,
            "last_seq": last_seq,
            "truncated": omitted or total != len(preview),
            **bounds,
        }

    @_captured_store_context
    async def usage_records(self, start_at: float, end_at: float) -> list[dict[str, Any]]:
        from .usage_statistics import summaries_from_events

        # PB uses an admin client: derive every message/turn scope from owned sessions.
        owner = _current_user_id()

        def read() -> list[dict[str, Any]]:
            pb = _pb()

            def pages(collection: str, query: dict[str, str]):
                page = 1
                while True:
                    response = pb.collection(collection).get_list(page, 200, query_params=query)
                    rows = self._page_items(response)
                    yield from rows
                    if page * 200 >= self._page_total(response) or not rows:
                        break
                    page += 1

            sessions = pb.collection("sessions").get_full_list(
                query_params={
                    "filter": _workspace_filter(f'user_id="{owner}"'),
                    "fields": "session_id,user_id,preferences_json",
                }
            )
            ids = [
                _validate_id(str(row.session_id), "session_id")
                for row in sessions
                if getattr(row, "user_id", None) == owner
                and _in_workspace(row)
                and not str(row.session_id).startswith("imported_")
            ]
            result: list[dict[str, Any]] = []
            for offset in range(0, len(ids), 30):
                owned = ids[offset : offset + 30]
                scope = " || ".join(f'session_id="{sid}"' for sid in owned)
                records: dict[str, dict[str, Any]] = {}
                message_metadata: dict[str, dict[str, Any]] = {}
                for row in pages(
                    "messages",
                    {
                        "filter": f'({scope}) && role="assistant" && msg_created_at >= {float(start_at)} && msg_created_at < {float(end_at)}',
                        "fields": "id,session_id,role,msg_created_at,events_json,metadata_json",
                        "sort": "msg_created_at,id",
                    },
                ):
                    if getattr(row, "session_id", None) not in owned:
                        continue
                    message_metadata[str(row.id)] = _json_loads(
                        getattr(row, "metadata_json", None), {}
                    )
                    records[str(row.id)] = {
                        "session_id": row.session_id,
                        "created_at": _to_float(getattr(row, "msg_created_at", None)),
                        "summaries": summaries_from_events(
                            _json_loads(getattr(row, "events_json", None), []),
                            message_metadata[str(row.id)],
                        ),
                    }
                message_ids = list(records)
                for start in range(0, len(message_ids), 30):
                    message_scope = " || ".join(
                        f'assistant_message_id="{_validate_id(mid, "message_id")}"'
                        for mid in message_ids[start : start + 30]
                    )
                    turns: dict[str, str] = {}
                    for row in pages(
                        "turns",
                        {
                            "filter": f"({scope}) && ({message_scope})",
                            "fields": "turn_id,session_id,assistant_message_id",
                            "sort": "turn_id",
                        },
                    ):
                        mid = str(getattr(row, "assistant_message_id", ""))
                        if (
                            mid in records
                            and getattr(row, "session_id", None) == records[mid]["session_id"]
                        ):
                            turns[_validate_id(str(row.turn_id), "turn_id")] = mid
                            records[mid]["turn_id"] = str(row.turn_id)
                    if not turns:
                        continue
                    turn_scope = " || ".join(f'turn_id="{tid}"' for tid in turns)
                    events: dict[str, list[dict[str, Any]]] = {tid: [] for tid in turns}
                    for row in pages(
                        "turn_events",
                        {
                            "filter": f'({turn_scope}) && (type="result" || type="done" || metadata_json.model != null)',
                            "fields": "turn_id,type,metadata_json,seq",
                            "sort": "turn_id,seq",
                        },
                    ):
                        tid = getattr(row, "turn_id", None)
                        if tid in events:
                            events[tid].append(
                                {
                                    "type": getattr(row, "type", ""),
                                    "metadata": _json_loads(
                                        getattr(row, "metadata_json", None), {}
                                    ),
                                }
                            )
                    for tid, values in events.items():
                        canonical = summaries_from_events(values, message_metadata[turns[tid]])
                        if canonical:
                            records[turns[tid]]["summaries"] = canonical
                result.extend(records.values())
            return result

        return await asyncio.to_thread(read)

    @_captured_store_context
    async def get_messages(self, session_id: str) -> list[dict[str, Any]]:
        if await self.get_session(session_id) is None:
            return []
        sid = _validate_id(session_id, "session_id")

        def _get() -> list[dict[str, Any]]:
            pb = _pb()
            records = pb.collection("messages").get_full_list(
                query_params={
                    "filter": f'session_id="{sid}"',
                    "sort": "msg_created_at",
                }
            )
            turns = pb.collection("turns").get_full_list(
                query_params={"filter": f'session_id="{sid}"'}
            )
            turns_by_message = {
                str(getattr(turn, "assistant_message_id", "") or ""): turn
                for turn in turns
                if getattr(turn, "assistant_message_id", None)
            }
            result: list[dict[str, Any]] = []
            for record in records:
                message = self._message_record_to_dict(record)
                turn = turns_by_message.get(str(record.id))
                if record.role == "assistant" and turn is not None:
                    turn_id = str(getattr(turn, "turn_id", turn.id) or "")
                    message["events"], message["trace"] = self._trace_preview(
                        pb, session_id=sid, turn_id=turn_id
                    )
                elif record.role == "assistant":
                    legacy_events = message["events"]
                    message["events"], omitted = compact_trace_preview(legacy_events)
                    message["trace"] = {
                        "turn_id": None,
                        "total": len(legacy_events),
                        "last_seq": 0,
                        "truncated": omitted,
                    }
                result.append(message)
            return result

        try:
            return await asyncio.to_thread(_get)
        except Exception as exc:
            logger.warning(f"get_messages failed: {exc}")
            return []

    @_captured_store_context
    async def get_messages_for_context(
        self, session_id: str, leaf_message_id: int | None = None
    ) -> list[dict[str, Any]]:
        # leaf_message_id (branch-aware context) is not supported on PocketBase
        # yet; fall back to the linear, append-only view.
        _ = leaf_message_id
        messages = await self.get_messages(session_id)
        return [
            {
                "id": m["id"],
                "role": m["role"],
                "content": m["content"] or "",
                "events": filter_ask_user_events(m.get("events")),
                "metadata": m.get("metadata") or {},
            }
            for m in messages
            if m["role"] in ("user", "assistant", "system")
        ]

    def _message_record_to_dict(self, record: Any) -> dict[str, Any]:
        raw_metadata = _json_loads(getattr(record, "metadata_json", None), {})
        metadata = dict(raw_metadata) if isinstance(raw_metadata, dict) else {}
        parent_message_id = metadata.pop(_PARENT_MESSAGE_METADATA_KEY, None)
        message = {
            "id": getattr(record, "id", ""),
            "session_id": getattr(record, "session_id", ""),
            "role": getattr(record, "role", ""),
            "content": getattr(record, "content", "") or "",
            "capability": getattr(record, "capability", "") or "",
            "events": _json_loads(getattr(record, "events_json", None), []),
            "attachments": _json_loads(getattr(record, "attachments_json", None), []),
            "metadata": metadata,
            "created_at": _to_float(getattr(record, "msg_created_at", None)),
        }
        if parent_message_id is not None:
            message["parent_message_id"] = parent_message_id
        return message

    # ------------------------------------------------------------------
    # Turns
    # ------------------------------------------------------------------

    @_captured_store_context
    async def begin_turn(
        self,
        session_id: str,
        capability: str = "",
        *,
        turn_id: str | None = None,
        owner_id: str = "",
        fencing_token: int = 0,
    ) -> dict[str, Any]:
        sid = _validate_id(session_id, "session_id")
        uid = _current_user_id()
        now = time.time()
        resolved_turn_id = _validate_id(
            turn_id or f"turn_{int(now * 1000)}_{uuid.uuid4().hex[:10]}", "turn_id"
        )

        def _create():
            # Guard: ensure the session exists AND belongs to the current user.
            if _find_session_record(_pb(), sid, uid) is None:
                raise ValueError(f"Session not found: {sid}")
            # Guard: no duplicate active turns
            session_turns = (
                _pb()
                .collection("turns")
                .get_full_list(query_params={"filter": f'session_id="{sid}"'})
            )
            active = [
                record
                for record in session_turns
                if getattr(record, "status", "") in _ACTIVE_TURN_STATUSES
            ]
            if active:
                raise ActiveTurnConflict(
                    f"Session already has an active turn: {active[0].turn_id}",
                    turn_id=str(active[0].turn_id),
                )
            return (
                _pb()
                .collection("turns")
                .create(
                    {
                        "turn_id": resolved_turn_id,
                        "session_id": sid,
                        "capability": capability or "",
                        "status": "running",
                        "error": "",
                        "turn_created_at": now,
                        "turn_updated_at": now,
                        "finished_at": None,
                        "owner_id": owner_id or "",
                        "fencing_token": max(0, int(fencing_token)),
                        "state_version": 1,
                        "failure_code": "",
                        "retryable": False,
                        "assistant_message_id": None,
                    }
                )
            )

        await asyncio.to_thread(_create)
        return {
            "id": resolved_turn_id,
            "turn_id": resolved_turn_id,
            "session_id": sid,
            "capability": capability or "",
            "status": "running",
            "error": "",
            "created_at": now,
            "updated_at": now,
            "finished_at": None,
            "last_seq": 0,
            "owner_id": owner_id or "",
            "fencing_token": max(0, int(fencing_token)),
            "state_version": 1,
            "failure_code": "",
            "retryable": False,
            "assistant_message_id": None,
        }

    @_captured_store_context
    async def create_turn(self, session_id: str, capability: str = "") -> dict[str, Any]:
        return await self.begin_turn(session_id, capability)

    @_captured_store_context
    async def get_turn(self, turn_id: str) -> dict[str, Any] | None:
        tid = _validate_id(turn_id, "turn_id")

        def _get():
            records = (
                _pb().collection("turns").get_full_list(query_params={"filter": f'turn_id="{tid}"'})
            )
            return records[0] if records else None

        record = await asyncio.to_thread(_get)
        if record and await self.get_session(str(getattr(record, "session_id", ""))) is None:
            return None
        return self._turn_record_to_dict(record) if record else None

    @_captured_store_context
    async def get_active_turn(self, session_id: str) -> dict[str, Any] | None:
        if await self.get_session(session_id) is None:
            return None
        sid = _validate_id(session_id, "session_id")

        def _get():
            records = (
                _pb()
                .collection("turns")
                .get_full_list(
                    query_params={"filter": f'session_id="{sid}"', "sort": "-turn_updated_at"}
                )
            )
            active = [
                record
                for record in records
                if getattr(record, "status", "") in _ACTIVE_TURN_STATUSES
            ]
            active.sort(key=lambda record: getattr(record, "turn_updated_at", 0), reverse=True)
            return active[0] if active else None

        record = await asyncio.to_thread(_get)
        return self._turn_record_to_dict(record) if record else None

    @_captured_store_context
    async def list_active_turns(self, session_id: str) -> list[dict[str, Any]]:
        if await self.get_session(session_id) is None:
            return []
        sid = _validate_id(session_id, "session_id")

        def _list():
            records = (
                _pb()
                .collection("turns")
                .get_full_list(
                    query_params={"filter": f'session_id="{sid}"', "sort": "-turn_updated_at"}
                )
            )
            active = [
                record
                for record in records
                if getattr(record, "status", "") in _ACTIVE_TURN_STATUSES
            ]
            active.sort(key=lambda record: getattr(record, "turn_updated_at", 0), reverse=True)
            return active

        try:
            records = await asyncio.to_thread(_list)
            return [self._turn_record_to_dict(r) for r in records]
        except Exception:
            return []

    @_captured_store_context
    async def list_orphaned_failed_turns(self, session_id: str) -> list[dict[str, Any]]:
        if await self.get_session(session_id) is None:
            return []
        sid = _validate_id(session_id, "session_id")

        def _list():
            return (
                _pb()
                .collection("turns")
                .get_full_list(
                    query_params={
                        "filter": f'session_id="{sid}" && status="failed"',
                        "sort": "turn_created_at",
                    }
                )
            )

        try:
            records = await asyncio.to_thread(_list)
        except Exception:
            logger.exception("Could not list orphaned failed turns for session %s", sid)
            return []
        return [
            self._turn_record_to_dict(record)
            for record in records
            if not getattr(record, "assistant_message_id", None)
        ]

    @_captured_store_context
    async def list_nonterminal_turns(self) -> list[dict[str, Any]]:
        def _list():
            records = (
                _pb().collection("turns").get_full_list(query_params={"sort": "turn_updated_at"})
            )
            return [
                record
                for record in records
                if getattr(record, "status", "") in _ACTIVE_TURN_STATUSES
            ]

        records = await asyncio.to_thread(_list)
        result = []
        for record in records:
            if await self.get_session(str(getattr(record, "session_id", ""))) is not None:
                result.append(self._turn_record_to_dict(record))
        return result

    @_captured_store_context
    async def transition_turn(
        self,
        turn_id: str,
        status: str,
        *,
        expected_status: str | None = None,
        fencing_token: int | None = None,
        error: str = "",
        failure_code: str = "",
        retryable: bool = False,
    ) -> bool:
        if status not in _ALL_TURN_STATUSES:
            raise ValueError(f"Unsupported turn status: {status}")
        if await self.get_turn(turn_id) is None:
            return False
        tid = _validate_id(turn_id, "turn_id")
        now = time.time()
        finished_at = now if status in _TERMINAL_TURN_STATUSES else None

        def _update():
            records = (
                _pb().collection("turns").get_full_list(query_params={"filter": f'turn_id="{tid}"'})
            )
            if not records:
                return False
            record = records[0]
            current_status = getattr(record, "status", "running")
            current_token = int(getattr(record, "fencing_token", 0) or 0)
            if expected_status is not None and current_status != expected_status:
                return False
            if fencing_token is not None and current_token != int(fencing_token):
                return False
            if current_status in _TERMINAL_TURN_STATUSES and current_status != status:
                return False
            _pb().collection("turns").update(
                record.id,
                {
                    "status": status,
                    "error": error or "",
                    "failure_code": failure_code or "",
                    "turn_updated_at": now,
                    "finished_at": finished_at,
                    "state_version": int(getattr(record, "state_version", 1) or 1) + 1,
                    "retryable": bool(retryable),
                },
            )
            return True

        try:
            updated = await asyncio.to_thread(_update)
        except Exception as exc:
            logger.warning(f"update_turn_status failed: {exc}")
            return False

        return updated

    @_captured_store_context
    async def update_turn_status(self, turn_id: str, status: str, error: str = "") -> bool:
        return await self.transition_turn(turn_id, status, error=error)

    def _turn_record_to_dict(self, record: Any) -> dict[str, Any]:
        turn_id = getattr(record, "turn_id", getattr(record, "id", ""))
        return {
            "id": turn_id,
            "turn_id": turn_id,
            "session_id": getattr(record, "session_id", ""),
            "capability": getattr(record, "capability", "") or "",
            "status": getattr(record, "status", "running") or "running",
            "error": getattr(record, "error", "") or "",
            "created_at": _to_float(getattr(record, "turn_created_at", None)),
            "updated_at": _to_float(getattr(record, "turn_updated_at", None)),
            "finished_at": _to_float(getattr(record, "finished_at", None)) or None,
            "last_seq": 0,
            "owner_id": getattr(record, "owner_id", "") or "",
            "fencing_token": int(getattr(record, "fencing_token", 0) or 0),
            "state_version": int(getattr(record, "state_version", 1) or 1),
            "failure_code": getattr(record, "failure_code", "") or "",
            "retryable": bool(getattr(record, "retryable", False)),
            "assistant_message_id": getattr(record, "assistant_message_id", None),
        }

    @_captured_store_context
    async def link_turn_message(self, turn_id: str, assistant_message_id: int | str) -> bool:
        if await self.get_turn(turn_id) is None:
            return False
        tid = _validate_id(turn_id, "turn_id")
        message_id = _validate_id(str(assistant_message_id), "assistant_message_id")

        def _link() -> bool:
            page = (
                _pb()
                .collection("turns")
                .get_list(1, 1, query_params={"filter": f'turn_id="{tid}"'})
            )
            turns = self._page_items(page)
            if not turns:
                return False
            record = turns[0]
            if getattr(record, "assistant_message_id", None):
                return False
            _pb().collection("turns").update(
                record.id,
                {
                    "assistant_message_id": message_id,
                    "turn_updated_at": time.time(),
                },
            )
            return True

        return await asyncio.to_thread(_link)

    @_captured_store_context
    async def get_message_trace(
        self,
        session_id: str,
        message_id: int | str,
        after_seq: int = 0,
        limit: int | None = None,
    ) -> dict[str, Any] | None:
        try:
            sid = _validate_id(session_id, "session_id")
            mid = _validate_id(str(message_id), "message_id")
        except ValueError:
            return None
        row_limit = 500 if limit is None else min(1000, max(1, int(limit)))
        uid = _current_user_id()

        def _get():
            pb = _pb()
            if _find_session_record(pb, sid, uid) is None:
                return None
            message_page = pb.collection("messages").get_list(
                1,
                1,
                query_params={"filter": f'id="{mid}" && session_id="{sid}"'},
            )
            messages = self._page_items(message_page)
            if not messages:
                return None
            turn_page = pb.collection("turns").get_list(
                1,
                1,
                query_params={"filter": f'assistant_message_id="{mid}"'},
            )
            turns = self._page_items(turn_page)
            if not turns:
                return None
            turn = turns[0]
            turn_id = str(getattr(turn, "turn_id", getattr(turn, "id", "")) or "")
            stats_page = pb.collection("turn_events").get_list(
                1,
                1,
                query_params={"filter": f'turn_id="{turn_id}"', "sort": "-seq"},
            )
            last_rows = self._page_items(stats_page)
            last_seq = int(getattr(last_rows[0], "seq", 0) or 0) if last_rows else 0
            event_page = pb.collection("turn_events").get_list(
                1,
                row_limit,
                query_params={
                    "filter": f'turn_id="{turn_id}" && seq>{max(0, int(after_seq))}',
                    "sort": "seq",
                },
            )
            events = [
                self._event_record_to_payload(row, sid, turn_id)
                for row in self._page_items(event_page)
            ]
            loaded_seq = int(events[-1]["seq"]) if events else max(0, int(after_seq))
            complete = loaded_seq >= last_seq
            return {
                "session_id": sid,
                "message_id": message_id,
                "turn_id": turn_id,
                "events": events,
                "total": self._page_total(stats_page),
                "last_seq": last_seq,
                "next_seq": None if complete else loaded_seq,
                "complete": complete,
            }

        return await asyncio.to_thread(_get)

    # ------------------------------------------------------------------
    # Turn events — synchronously durable before terminal transition
    # ------------------------------------------------------------------

    @_captured_store_context
    async def append_turn_event(self, turn_id: str, event: dict[str, Any]) -> dict[str, Any]:
        """Single-event convenience wrapper over ``append_turn_events``."""
        persisted = await self.append_turn_events(turn_id, [event])
        return persisted[0]

    @_captured_store_context
    async def append_turn_events(
        self, turn_id: str, events: list[dict[str, Any]]
    ) -> list[dict[str, Any]]:
        return await self.append_events(turn_id, events)

    @_captured_store_context
    async def append_events(
        self,
        turn_id: str,
        events: list[dict[str, Any]],
        *,
        fencing_token: int | None = None,
    ) -> list[dict[str, Any]]:
        """Idempotently persist a batch before the caller can publish DONE."""
        if await self.get_turn(turn_id) is None:
            raise ValueError("Turn not found in this workspace")
        tid = _validate_id(turn_id, "turn_id")

        def _persist() -> list[dict[str, Any]]:
            pb = _pb()
            if fencing_token is not None:
                turns = pb.collection("turns").get_full_list(
                    query_params={"filter": f'turn_id="{tid}"'}
                )
                if not turns or int(getattr(turns[0], "fencing_token", 0) or 0) != int(
                    fencing_token
                ):
                    raise RuntimeError(f"Turn lease lost: {tid}")

            existing_rows = pb.collection("turn_events").get_full_list(
                query_params={"filter": f'turn_id="{tid}"', "sort": "seq"}
            )
            existing_by_seq = {
                int(getattr(record, "seq", 0) or 0): record for record in existing_rows
            }
            next_seq = max(existing_by_seq, default=0) + 1
            payloads: list[dict[str, Any]] = []
            now = time.time()
            for event in events:
                payload = dict(event)
                seq = int(payload.get("seq") or 0)
                if seq <= 0:
                    seq = next_seq
                    next_seq += 1
                else:
                    next_seq = max(next_seq, seq + 1)
                payload["turn_id"] = payload.get("turn_id") or tid
                payload["seq"] = seq
                payload["timestamp"] = float(payload.get("timestamp") or now)

                existing = existing_by_seq.get(seq)
                if existing is not None:
                    same = (
                        (getattr(existing, "type", "") or "") == str(payload.get("type", ""))
                        and (getattr(existing, "source", "") or "")
                        == str(payload.get("source", ""))
                        and (getattr(existing, "stage", "") or "") == str(payload.get("stage", ""))
                        and (getattr(existing, "content", "") or "")
                        == str(payload.get("content", "") or "")[:10000]
                        and _json_loads(getattr(existing, "metadata_json", None), {})
                        == (payload.get("metadata") or {})
                    )
                    if not same:
                        raise ValueError(f"Turn event conflict: {tid} seq={seq}")
                    payload["timestamp"] = _to_float(
                        getattr(existing, "event_timestamp", None), payload["timestamp"]
                    )
                    payloads.append(payload)
                    continue

                record = pb.collection("turn_events").create(
                    {
                        "turn_id": tid,
                        "session_id": payload.get("session_id", ""),
                        "seq": seq,
                        "type": payload.get("type", ""),
                        "source": payload.get("source", ""),
                        "stage": payload.get("stage", ""),
                        "content": str(payload.get("content", ""))[:10000],
                        "metadata_json": payload.get("metadata", {}),
                        "event_timestamp": payload["timestamp"],
                    }
                )
                existing_by_seq[seq] = record
                payloads.append(payload)
            return payloads

        return await asyncio.to_thread(_persist)

    @_captured_store_context
    async def get_turn_events(self, turn_id: str, after_seq: int = 0) -> list[dict[str, Any]]:
        """Retrieve persisted turn events from PocketBase (post-turn replay)."""
        if await self.get_turn(turn_id) is None:
            return []
        tid = _validate_id(turn_id, "turn_id")

        def _get():
            filter_str = f'turn_id="{tid}"'
            if after_seq > 0:
                filter_str += f" && seq > {after_seq}"
            return (
                _pb()
                .collection("turn_events")
                .get_full_list(query_params={"filter": filter_str, "sort": "seq"})
            )

        try:
            records = await asyncio.to_thread(_get)
            return [
                {
                    "type": getattr(r, "type", ""),
                    "source": getattr(r, "source", ""),
                    "stage": getattr(r, "stage", ""),
                    "content": getattr(r, "content", "") or "",
                    "metadata": _json_loads(getattr(r, "metadata_json", None), {}),
                    "session_id": getattr(r, "session_id", ""),
                    "turn_id": tid,
                    "seq": int(getattr(r, "seq", 0)),
                    "timestamp": _to_float(getattr(r, "event_timestamp", None)),
                }
                for r in records
            ]
        except Exception as exc:
            logger.warning(f"get_turn_events failed: {exc}")
            return []

    @_captured_store_context
    async def get_events(self, turn_id: str, after_seq: int = 0) -> list[dict[str, Any]]:
        return await self.get_turn_events(turn_id, after_seq)