qi-runtime-postgres 2.0.2__py3-none-any.whl

qi_runtime_postgres/store.py

@@ -0,0 +1,1665 @@
+"""PostgreSQL 上的 Session、Submission、Outbox 与 Lease 统一事实存储。"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+import time
+from collections.abc import Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from typing import Any, LiteralString
+from uuid import NAMESPACE_URL, uuid5
+
+import psycopg
+from psycopg import sql as pg_sql
+from psycopg.rows import dict_row
+from psycopg_pool import ConnectionPool
+
+from qi_protocol import (
+    CommittedSessionEvent,
+    Submission,
+    SubmissionReceipt,
+    SubmissionStatus,
+)
+from qi_runtime_plane import ClaimedSubmission, SessionLease
+from qi_session import Session, SessionEvent, SessionHeader, SessionProjection
+from qi_session.store_errors import FencingTokenRejected, RuntimeStoreError, SequenceConflict
+
+RUNTIME_STORE_SCHEMA = 1
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS runtime_schema (
+  version BIGINT PRIMARY KEY,
+  applied_at_ms BIGINT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS sessions (
+  session_id TEXT PRIMARY KEY,
+  header_json TEXT NOT NULL,
+  last_sequence BIGINT NOT NULL DEFAULT -1,
+  created_at_ms BIGINT NOT NULL,
+  updated_at_ms BIGINT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session_events (
+  session_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  event_id TEXT NOT NULL UNIQUE,
+  event_type TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  envelope_json TEXT NOT NULL,
+  recorded_at_ms BIGINT NOT NULL,
+  PRIMARY KEY(session_id, sequence),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_session_events_type
+  ON session_events(session_id, event_type, sequence);
+CREATE TABLE IF NOT EXISTS submissions (
+  operation_id TEXT PRIMARY KEY,
+  submission_id TEXT NOT NULL UNIQUE,
+  session_id TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  source_json TEXT NOT NULL,
+  expected_revision BIGINT,
+  status TEXT NOT NULL,
+  accepted_sequence BIGINT NOT NULL,
+  accepted_cursor BIGINT NOT NULL DEFAULT 0,
+  claimed_by TEXT,
+  claim_expires_at_ms BIGINT,
+  attempts BIGINT NOT NULL DEFAULT 0,
+  last_error TEXT,
+  created_at_ms BIGINT NOT NULL,
+  updated_at_ms BIGINT NOT NULL,
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_submissions_claim
+  ON submissions(status, claim_expires_at_ms, created_at_ms, operation_id);
+CREATE INDEX IF NOT EXISTS idx_submissions_session
+  ON submissions(session_id, status, accepted_sequence);
+CREATE TABLE IF NOT EXISTS session_leases (
+  session_id TEXT PRIMARY KEY,
+  owner_id TEXT NOT NULL,
+  generation BIGINT NOT NULL,
+  expires_at_ms BIGINT NOT NULL,
+  updated_at_ms BIGINT NOT NULL,
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS event_outbox (
+  cursor BIGSERIAL PRIMARY KEY,
+  event_id TEXT NOT NULL UNIQUE,
+  session_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  event_type TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  recorded_at_ms BIGINT NOT NULL,
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_event_outbox_session
+  ON event_outbox(session_id, cursor);
+CREATE TABLE IF NOT EXISTS approvals (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  turn_id TEXT NOT NULL DEFAULT '',
+  step_id TEXT NOT NULL DEFAULT '',
+  tool_call_id TEXT NOT NULL DEFAULT '',
+  operation_id TEXT NOT NULL DEFAULT '',
+  tool_name TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  revision BIGINT NOT NULL DEFAULT 0,
+  arguments_json TEXT NOT NULL DEFAULT '{}',
+  reason TEXT NOT NULL DEFAULT '',
+  actor_json TEXT,
+  resolution_reason TEXT,
+  expires_at TEXT,
+  created_at TEXT NOT NULL,
+  resolved_at TEXT,
+  requested_sequence BIGINT NOT NULL DEFAULT -1,
+  resolved_sequence BIGINT,
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_approvals_pending
+  ON approvals(status, expires_at, session_id);
+CREATE TABLE IF NOT EXISTS session_snapshots (
+  session_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  snapshot_json TEXT NOT NULL,
+  created_at_ms BIGINT NOT NULL,
+  PRIMARY KEY(session_id, sequence),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS projection_offsets (
+  projector TEXT PRIMARY KEY,
+  cursor BIGINT NOT NULL,
+  updated_at_ms BIGINT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS session_projection (
+  session_id TEXT NOT NULL,
+  projection_key TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  payload_json TEXT NOT NULL,
+  PRIMARY KEY(session_id, projection_key),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS context_window_projection (
+  session_id TEXT NOT NULL,
+  window_id TEXT NOT NULL,
+  previous_window_id TEXT,
+  started_sequence BIGINT NOT NULL,
+  trigger TEXT NOT NULL,
+  PRIMARY KEY(session_id, window_id),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS context_note_projection (
+  session_id TEXT NOT NULL,
+  path TEXT NOT NULL,
+  content TEXT NOT NULL,
+  updated_sequence BIGINT NOT NULL,
+  PRIMARY KEY(session_id, path),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE TABLE IF NOT EXISTS context_history_projection (
+  session_id TEXT NOT NULL,
+  item_id TEXT NOT NULL,
+  window_id TEXT NOT NULL,
+  sequence BIGINT NOT NULL,
+  role TEXT NOT NULL,
+  tool_name TEXT,
+  content TEXT NOT NULL,
+  PRIMARY KEY(session_id, item_id),
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_context_history_window
+  ON context_history_projection(session_id, window_id, sequence);
+CREATE TABLE IF NOT EXISTS user_input_requests (
+  request_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  turn_id TEXT NOT NULL DEFAULT '',
+  prompt TEXT NOT NULL,
+  input_schema_json TEXT NOT NULL DEFAULT '{}',
+  status TEXT NOT NULL DEFAULT 'pending',
+  outcome TEXT,
+  value_json TEXT,
+  actor_json TEXT,
+  resolution_reason TEXT,
+  revision BIGINT NOT NULL DEFAULT 0,
+  expires_at_ms BIGINT NOT NULL,
+  requested_sequence BIGINT NOT NULL,
+  resolved_sequence BIGINT,
+  FOREIGN KEY(session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_user_input_pending
+  ON user_input_requests(status, expires_at_ms, session_id);
+"""
+
+
+class PostgresRuntimeStore:
+    """将事件、队列投影和 Outbox 放在同一 PostgreSQL 提交边界内。
+
+    Session sequence 是会话内顺序, Outbox cursor 是跨会话的发布位置。
+    两者不能互换; 业务投影可重建, 不能绕过事件直接修改业务终态。
+    """
+
+    def __init__(
+        self, dsn: str, *, min_size: int = 1, max_size: int = 10, timeout: float = 30
+    ) -> None:
+        self._closed = False
+        self._pool_lock = threading.Lock()
+        self._opened = False
+        self._pool: ConnectionPool[psycopg.Connection[dict[str, Any]]] = ConnectionPool(
+            dsn,
+            min_size=min_size,
+            max_size=max_size,
+            timeout=timeout,
+            kwargs={"row_factory": dict_row},
+            open=False,
+        )
+
+    async def migrate(self) -> None:
+        await asyncio.to_thread(self._migrate_sync)
+
+    async def create(self, header: SessionHeader) -> None:
+        await asyncio.to_thread(self._create_sync, header)
+
+    async def append(self, session_id: str, events: Sequence[SessionEvent]) -> None:
+        if events:
+            await asyncio.to_thread(self._append_sync, session_id, tuple(events), None, None)
+
+    async def append_fenced(
+        self,
+        session_id: str,
+        events: Sequence[SessionEvent],
+        *,
+        expected_sequence: int,
+        fencing_token: int,
+    ) -> tuple[CommittedSessionEvent, ...]:
+        return await asyncio.to_thread(
+            self._append_sync,
+            session_id,
+            tuple(events),
+            expected_sequence,
+            fencing_token,
+        )
+
+    async def flush(self, session_id: str) -> None:
+        # append 返回前已 COMMIT; 此处没有待刷缓冲, 仍保留 Event Store 端口约定。
+        del session_id
+
+    async def load(self, session_id: str) -> tuple[SessionHeader, tuple[SessionEvent, ...]]:
+        return await asyncio.to_thread(self._load_sync, session_id)
+
+    async def inspect(self, session_id: str) -> tuple[SessionHeader, tuple[SessionEvent, ...]]:
+        return await self.load(session_id)
+
+    async def read_from(self, session_id: str, from_sequence: int) -> tuple[SessionEvent, ...]:
+        if from_sequence < 0:
+            raise ValueError("from_sequence must be non-negative")
+        return await asyncio.to_thread(self._read_range_sync, session_id, from_sequence, None, None)
+
+    async def read_before(
+        self,
+        session_id: str,
+        before_sequence: int,
+        limit: int,
+    ) -> tuple[SessionEvent, ...]:
+        if before_sequence < 0 or limit < 1:
+            raise ValueError("before_sequence must be non-negative and limit positive")
+        return await asyncio.to_thread(
+            self._read_range_sync,
+            session_id,
+            None,
+            before_sequence,
+            limit,
+        )
+
+    async def read_after(
+        self,
+        session_id: str,
+        after_sequence: int,
+        limit: int,
+    ) -> tuple[SessionEvent, ...]:
+        if after_sequence < -1 or limit < 1:
+            raise ValueError("after_sequence must be at least -1 and limit positive")
+        return await asyncio.to_thread(
+            self._read_range_sync,
+            session_id,
+            after_sequence + 1,
+            None,
+            limit,
+        )
+
+    async def read_raw(self, session_id: str) -> bytes:
+        header, events = await self.load(session_id)
+        rows = [
+            {"type": "session", **header.model_dump(mode="json")},
+            *(event.wire_dump() for event in events),
+        ]
+        return b"".join(
+            json.dumps(row, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + b"\n"
+            for row in rows
+        )
+
+    async def list_headers(self) -> tuple[SessionHeader, ...]:
+        return await asyncio.to_thread(self._list_headers_sync)
+
+    async def list_projections(self, key: str) -> tuple[SessionProjection, ...]:
+        return await asyncio.to_thread(self._list_projections_sync, key)
+
+    async def search_context_history(
+        self,
+        session_id: str,
+        query: str,
+        limit: int,
+    ) -> tuple[int, ...]:
+        return await asyncio.to_thread(self._search_context_history_sync, session_id, query, limit)
+
+    async def get_user_input(self, request_id: str) -> Mapping[str, Any] | None:
+        return await asyncio.to_thread(self._get_user_input_sync, request_id)
+
+    async def get_approval(self, approval_id: str) -> Mapping[str, Any] | None:
+        return await asyncio.to_thread(self._get_approval_sync, approval_id)
+
+    async def list_pending_approvals(
+        self,
+        *,
+        session_ids: Sequence[str] | None = None,
+    ) -> tuple[Mapping[str, Any], ...]:
+        return await asyncio.to_thread(self._list_pending_approvals_sync, session_ids)
+
+    async def list_pending_user_inputs(
+        self,
+        *,
+        session_ids: Sequence[str] | None = None,
+    ) -> tuple[Mapping[str, Any], ...]:
+        return await asyncio.to_thread(self._list_pending_user_inputs_sync, session_ids)
+
+    async def rebuild_projections(self) -> None:
+        """仅从事实事件重建所有本地查询投影。"""
+
+        await asyncio.to_thread(self._rebuild_projections_sync)
+
+    async def read_snapshot(self, session_id: str) -> Mapping[str, Any] | None:
+        return await asyncio.to_thread(self._read_snapshot_sync, session_id)
+
+    async def close(self) -> None:
+        self._closed = True
+        await asyncio.to_thread(self._pool.close)
+
+    async def get_receipt(
+        self,
+        operation_id: str,
+        *,
+        duplicate: bool = False,
+    ) -> SubmissionReceipt | None:
+        return await asyncio.to_thread(self._get_receipt_sync, operation_id, duplicate)
+
+    async def get_submission(self, operation_id: str) -> Submission | None:
+        return await asyncio.to_thread(self._get_submission_sync, operation_id)
+
+    async def claim_next(
+        self,
+        worker_id: str,
+        *,
+        lease_seconds: float = 30,
+    ) -> ClaimedSubmission | None:
+        """按会话接纳顺序领取命令, 过期 claim 可以再次领取。
+
+        Claim 不是一次性执行保证, 也不是 Session 写权限; 后者由独立 Lease 校验。
+        重试仍需依赖 operation_id 和执行账本避免重复副作用。
+        """
+        return await asyncio.to_thread(self._claim_next_sync, worker_id, lease_seconds)
+
+    async def release(self, operation_id: str, *, error: str | None = None) -> None:
+        await asyncio.to_thread(self._release_submission_sync, operation_id, error)
+
+    async def pending(self, session_id: str | None = None) -> tuple[Submission, ...]:
+        return await asyncio.to_thread(self._pending_sync, session_id)
+
+    async def unfinished_counts(self, session_id: str) -> tuple[int, int]:
+        return await asyncio.to_thread(self._unfinished_counts_sync, session_id)
+
+    async def acquire(
+        self,
+        session_id: str,
+        owner_id: str,
+        *,
+        ttl_seconds: float = 30,
+    ) -> SessionLease | None:
+        return await asyncio.to_thread(self._acquire_sync, session_id, owner_id, ttl_seconds)
+
+    async def renew(self, lease: SessionLease, *, ttl_seconds: float = 30) -> SessionLease:
+        return await asyncio.to_thread(self._renew_sync, lease, ttl_seconds)
+
+    async def release_lease(self, lease: SessionLease) -> None:
+        await asyncio.to_thread(self._release_lease_sync, lease)
+
+    async def read_outbox(
+        self,
+        after_cursor: int,
+        *,
+        limit: int = 100,
+    ) -> tuple[CommittedSessionEvent, ...]:
+        return await asyncio.to_thread(self._read_outbox_sync, after_cursor, limit)
+
+    async def latest_outbox_cursor(self) -> int:
+        return await asyncio.to_thread(self._latest_outbox_cursor_sync)
+
+    @contextmanager
+    def _connection(self) -> Iterator[psycopg.Connection[dict[str, Any]]]:
+        with self._pool_lock:
+            if self._closed:
+                raise RuntimeStoreError("runtime store is closed")
+            if not self._opened:
+                self._pool.open(wait=True)
+                self._opened = True
+        with self._pool.connection() as connection:
+            yield connection
+
+    def _migrate_sync(self) -> None:
+        with self._connection() as connection:
+            # Serialize setup across processes, including first creation of schema metadata.
+            connection.execute("SELECT pg_advisory_xact_lock(716901, 1)")
+            for statement in _SCHEMA.split(";"):
+                if statement.strip():
+                    connection.execute(pg_sql.SQL(statement))
+            versions = tuple(
+                int(row["version"])
+                for row in connection.execute(
+                    "SELECT version FROM runtime_schema ORDER BY version"
+                ).fetchall()
+            )
+            if not versions:
+                connection.execute(
+                    "INSERT INTO runtime_schema(version, applied_at_ms) VALUES (%s, %s)",
+                    (RUNTIME_STORE_SCHEMA, _now_ms()),
+                )
+            elif versions != (RUNTIME_STORE_SCHEMA,):
+                raise RuntimeStoreError(f"unsupported Runtime Store schema versions: {versions}")
+
+    def _create_sync(self, header: SessionHeader) -> None:
+        now = _now_ms()
+        payload = json.dumps(header.model_dump(mode="json"), ensure_ascii=False)
+        with self._connection() as connection:
+            try:
+                connection.execute(
+                    """INSERT INTO sessions(
+                         session_id, header_json, last_sequence, created_at_ms, updated_at_ms)
+                       VALUES (%s, %s, -1, %s, %s)""",
+                    (header.id, payload, now, now),
+                )
+                connection.commit()
+            except psycopg.IntegrityError as exc:
+                raise RuntimeStoreError(f"session already exists: {header.id}") from exc
+
+    def _append_sync(
+        self,
+        session_id: str,
+        events: tuple[SessionEvent, ...],
+        expected_sequence: int | None,
+        fencing_token: int | None,
+    ) -> tuple[CommittedSessionEvent, ...]:
+        with self._connection() as connection:
+            try:
+                connection.execute("SELECT pg_advisory_xact_lock(716901, 2)")
+                row = connection.execute(
+                    "SELECT last_sequence FROM sessions WHERE session_id=%s FOR UPDATE",
+                    (session_id,),
+                ).fetchone()
+                if row is None:
+                    raise KeyError(f"unknown session: {session_id}")
+                current = int(row["last_sequence"])
+                if expected_sequence is not None and expected_sequence != current + 1:
+                    raise SequenceConflict(
+                        f"session {session_id!r} expected sequence {expected_sequence}, "
+                        f"actual {current + 1}"
+                    )
+                if fencing_token is not None:
+                    self._check_fencing(connection, session_id, fencing_token)
+                committed: list[CommittedSessionEvent] = []
+                for offset, event in enumerate(events):
+                    sequence = current + 1 + offset
+                    if event.sequence != sequence:
+                        raise SequenceConflict(
+                            f"event sequence {event.sequence} does not follow durable {current}"
+                        )
+                    committed.append(self._insert_event(connection, session_id, event))
+                if events:
+                    connection.execute(
+                        "UPDATE sessions SET last_sequence=%s, updated_at_ms=%s WHERE "
+                        "session_id=%s",
+                        (events[-1].sequence, _now_ms(), session_id),
+                    )
+                connection.commit()
+                return tuple(committed)
+            except BaseException:
+                connection.rollback()
+                raise
+
+    def _insert_event(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> CommittedSessionEvent:
+        event_id = _event_id(session_id, event.sequence)
+        envelope = event.wire_dump()
+        payload_json = json.dumps(dict(event.data), ensure_ascii=False, separators=(",", ":"))
+        connection.execute(
+            """INSERT INTO session_events(
+                 session_id, sequence, event_id, event_type, payload_json,
+                 envelope_json, recorded_at_ms)
+               VALUES (%s, %s, %s, %s, %s, %s, %s)""",
+            (
+                session_id,
+                event.sequence,
+                event_id,
+                event.type,
+                payload_json,
+                json.dumps(envelope, ensure_ascii=False, separators=(",", ":")),
+                event.time,
+            ),
+        )
+        cursor = connection.execute(
+            """INSERT INTO event_outbox(
+                 event_id, session_id, sequence, event_type, payload_json, recorded_at_ms)
+               VALUES (%s, %s, %s, %s, %s, %s) RETURNING cursor""",
+            (event_id, session_id, event.sequence, event.type, payload_json, event.time),
+        ).fetchone()
+        assert cursor is not None
+        committed = CommittedSessionEvent(
+            eventId=event_id,
+            sessionId=session_id,
+            sequence=event.sequence,
+            eventType=event.type,
+            payload=dict(event.data),
+            recordedAtMs=event.time,
+            durableCursor=int(cursor["cursor"]),
+        )
+        self._project_event(
+            connection,
+            session_id,
+            event,
+            durable_cursor=committed.durable_cursor,
+        )
+        return committed
+
+    def _project_submission(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+        durable_cursor: int,
+    ) -> None:
+        """在 Event 与 Outbox 相同事务内维护可重建 Submission 投影。"""
+
+        data = event.data
+        operation_id = str(data["operation_id"])
+        submission_id = str(data["submission_id"])
+        source = data.get("source", {})
+        payload = data.get("payload", {})
+        connection.execute(
+            """INSERT INTO submissions(
+                 operation_id, submission_id, session_id, kind, payload_json,
+                 source_json, expected_revision, status, accepted_sequence,
+                 accepted_cursor, created_at_ms, updated_at_ms)
+               VALUES (%s, %s, %s, %s, %s, %s, %s, 'pending', %s, %s, %s, %s)""",
+            (
+                operation_id,
+                submission_id,
+                session_id,
+                str(data["kind"]),
+                json.dumps(payload, ensure_ascii=False),
+                json.dumps(source, ensure_ascii=False),
+                data.get("expected_revision"),
+                event.sequence,
+                durable_cursor,
+                event.time,
+                event.time,
+            ),
+        )
+
+    def _load_sync(self, session_id: str) -> tuple[SessionHeader, tuple[SessionEvent, ...]]:
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT header_json FROM sessions WHERE session_id=%s",
+                (session_id,),
+            ).fetchone()
+            if row is None:
+                raise KeyError(f"unknown session: {session_id}")
+            header = SessionHeader.model_validate_json(str(row["header_json"]))
+            events = tuple(
+                _event_from_json(session_id, str(item["envelope_json"]))
+                for item in connection.execute(
+                    """SELECT envelope_json FROM session_events
+                       WHERE session_id=%s ORDER BY sequence""",
+                    (session_id,),
+                ).fetchall()
+            )
+        validated = Session(header, events)
+        return header, validated.events
+
+    def _read_range_sync(
+        self,
+        session_id: str,
+        from_sequence: int | None,
+        before_sequence: int | None,
+        limit: int | None,
+    ) -> tuple[SessionEvent, ...]:
+        clauses: list[LiteralString] = ["session_id=%s"]
+        values: list[Any] = [session_id]
+        if from_sequence is not None:
+            clauses.append("sequence>=%s")
+            values.append(from_sequence)
+        if before_sequence is not None:
+            clauses.append("sequence<%s")
+            values.append(before_sequence)
+        order = "DESC" if before_sequence is not None else "ASC"
+        sql = "SELECT envelope_json FROM session_events WHERE " + " AND ".join(clauses)
+        sql += f" ORDER BY sequence {order}"
+        if limit is not None:
+            sql += " LIMIT %s"
+            values.append(limit)
+        with self._connection() as connection:
+            rows = connection.execute(pg_sql.SQL(sql), tuple(values)).fetchall()
+        events = tuple(_event_from_json(session_id, str(row["envelope_json"])) for row in rows)
+        return tuple(reversed(events)) if before_sequence is not None else events
+
+    def _list_headers_sync(self) -> tuple[SessionHeader, ...]:
+        with self._connection() as connection:
+            rows = connection.execute(
+                "SELECT header_json FROM sessions ORDER BY created_at_ms DESC, session_id"
+            ).fetchall()
+        return tuple(SessionHeader.model_validate_json(str(row["header_json"])) for row in rows)
+
+    def _search_context_history_sync(
+        self,
+        session_id: str,
+        query: str,
+        limit: int,
+    ) -> tuple[int, ...]:
+        with self._connection() as connection:
+            rows = connection.execute(
+                """SELECT sequence FROM context_history_projection
+                   WHERE session_id=%s AND strpos(content, %s) > 0
+                   ORDER BY sequence DESC LIMIT %s""",
+                (session_id, query, max(1, limit)),
+            ).fetchall()
+        return tuple(int(row["sequence"]) for row in rows)
+
+    def _get_user_input_sync(self, request_id: str) -> Mapping[str, Any] | None:
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT * FROM user_input_requests WHERE request_id=%s",
+                (request_id,),
+            ).fetchone()
+        return None if row is None else _public_user_input(dict(row))
+
+    def _get_approval_sync(self, approval_id: str) -> Mapping[str, Any] | None:
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT * FROM approvals WHERE id=%s",
+                (approval_id,),
+            ).fetchone()
+        return None if row is None else _public_approval(dict(row))
+
+    def _list_pending_approvals_sync(
+        self,
+        session_ids: Sequence[str] | None,
+    ) -> tuple[Mapping[str, Any], ...]:
+        sql = "SELECT * FROM approvals WHERE status='pending'"
+        parameters: tuple[Any, ...] = ()
+        if session_ids is not None:
+            if not session_ids:
+                return ()
+            placeholders = ",".join("%s" for _ in session_ids)
+            sql += f" AND session_id IN ({placeholders})"
+            parameters = tuple(session_ids)
+        sql += " ORDER BY requested_sequence, id"
+        with self._connection() as connection:
+            rows = connection.execute(pg_sql.SQL(sql), parameters).fetchall()
+        return tuple(_public_approval(dict(row)) for row in rows)
+
+    def _list_pending_user_inputs_sync(
+        self,
+        session_ids: Sequence[str] | None,
+    ) -> tuple[Mapping[str, Any], ...]:
+        sql = "SELECT * FROM user_input_requests WHERE status='pending'"
+        parameters: tuple[Any, ...] = ()
+        if session_ids is not None:
+            if not session_ids:
+                return ()
+            placeholders = ",".join("%s" for _ in session_ids)
+            sql += f" AND session_id IN ({placeholders})"
+            parameters = tuple(session_ids)
+        sql += " ORDER BY requested_sequence, request_id"
+        with self._connection() as connection:
+            rows = connection.execute(pg_sql.SQL(sql), parameters).fetchall()
+        return tuple(_public_user_input(dict(row)) for row in rows)
+
+    def _list_projections_sync(self, key: str) -> tuple[SessionProjection, ...]:
+        with self._connection() as connection:
+            rows = connection.execute(
+                """SELECT session_id, sequence, payload_json
+                   FROM session_projection
+                   WHERE projection_key=%s ORDER BY session_id""",
+                (key,),
+            ).fetchall()
+        return tuple(
+            SessionProjection(
+                session_id=str(row["session_id"]),
+                key=key,
+                sequence=int(row["sequence"]),
+                value=json.loads(str(row["payload_json"])),
+            )
+            for row in rows
+        )
+
+    def _read_snapshot_sync(self, session_id: str) -> Mapping[str, Any] | None:
+        with self._connection() as connection:
+            row = connection.execute(
+                """SELECT snapshot_json FROM session_snapshots
+                   WHERE session_id=%s ORDER BY sequence DESC LIMIT 1""",
+                (session_id,),
+            ).fetchone()
+        return None if row is None else json.loads(str(row["snapshot_json"]))
+
+    def _project_event(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+        *,
+        durable_cursor: int,
+    ) -> None:
+        """在事实事件事务内更新可删除投影, 避免出现先发布后投影的窗口。"""
+
+        self._project_submission_event(connection, session_id, event, durable_cursor)
+        self._project_subagent(connection, session_id, event)
+        self._project_channel(connection, session_id, event)
+        self._project_context(connection, session_id, event)
+        self._project_user_input(connection, session_id, event)
+        self._project_approval(connection, session_id, event)
+        self._project_snapshot(connection, session_id, event, durable_cursor)
+        connection.execute(
+            """INSERT INTO projection_offsets(projector, cursor, updated_at_ms)
+               VALUES ('runtime-inline', %s, %s)
+               ON CONFLICT(projector) DO UPDATE SET
+                 cursor=excluded.cursor,
+                 updated_at_ms=excluded.updated_at_ms""",
+            (durable_cursor, _now_ms()),
+        )
+
+    def _project_submission_event(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+        durable_cursor: int,
+    ) -> None:
+        if event.type == "submission/accepted":
+            self._project_submission(connection, session_id, event, durable_cursor)
+            return
+        if event.type not in {"submission/completed", "submission/failed"}:
+            return
+        operation_id = str(event.data.get("operation_id", ""))
+        status = "completed" if event.type == "submission/completed" else "failed"
+        changed = connection.execute(
+            """UPDATE submissions SET status=%s, claimed_by=NULL,
+               claim_expires_at_ms=NULL, last_error=%s, updated_at_ms=%s
+               WHERE operation_id=%s AND session_id=%s""",
+            (
+                status,
+                event.data.get("error") if status == "failed" else None,
+                event.time,
+                operation_id,
+                session_id,
+            ),
+        ).rowcount
+        if changed != 1:
+            raise RuntimeStoreError(
+                f"submission terminal event references unknown operation {operation_id!r}"
+            )
+
+    def _project_user_input(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> None:
+        data = dict(event.data)
+        if event.type == "user-input/requested":
+            connection.execute(
+                """INSERT INTO user_input_requests(
+                     request_id, session_id, turn_id, prompt, input_schema_json,
+                     expires_at_ms, requested_sequence)
+                   VALUES (%s, %s, %s, %s, %s, %s, %s) ON CONFLICT DO NOTHING""",
+                (
+                    str(data["request_id"]),
+                    session_id,
+                    str(data.get("turn_id") or event.turn_id or ""),
+                    str(data.get("prompt", "")),
+                    json.dumps(data.get("input_schema", {}), ensure_ascii=False),
+                    int(data["expires_at_ms"]),
+                    event.sequence,
+                ),
+            )
+            return
+        if event.type != "user-input/resolved":
+            return
+        request_id = str(data["request_id"])
+        expected_revision = int(data.get("expected_revision", 0))
+        changed = connection.execute(
+            """UPDATE user_input_requests
+               SET status='resolved', outcome=%s, value_json=%s, actor_json=%s,
+                   resolution_reason=%s, revision=revision+1, resolved_sequence=%s
+               WHERE request_id=%s AND session_id=%s AND status='pending' AND revision=%s""",
+            (
+                str(data["outcome"]),
+                json.dumps(data.get("value"), ensure_ascii=False),
+                json.dumps(data.get("actor", {}), ensure_ascii=False),
+                data.get("reason"),
+                event.sequence,
+                request_id,
+                session_id,
+                expected_revision,
+            ),
+        ).rowcount
+        if changed != 1:
+            raise RuntimeStoreError(
+                f"user input {request_id!r} was resolved concurrently or is missing"
+            )
+
+    def _project_approval(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> None:
+        data = dict(event.data)
+        if event.type == "approval/requested":
+            timeout_seconds = max(0.0, float(data.get("timeout_seconds", 300)))
+            expires_at = _iso_time(event.time + int(timeout_seconds * 1000))
+            connection.execute(
+                """INSERT INTO approvals(
+                     id, session_id, turn_id, step_id, tool_call_id, operation_id,
+                     tool_name, status, revision, arguments_json, reason, expires_at,
+                     created_at, requested_sequence)
+                   VALUES (%s, %s, %s, %s, %s, %s, %s, 'pending', 0, %s, %s, %s, %s, %s) ON
+                   CONFLICT DO NOTHING""",
+                (
+                    str(data["approval_id"]),
+                    session_id,
+                    str(data.get("turn_id") or event.turn_id or ""),
+                    str(data.get("step_id") or event.step_id or ""),
+                    str(data.get("tool_call_id", "")),
+                    str(data.get("operation_id", "")),
+                    str(data.get("tool_name", "")),
+                    json.dumps(data.get("arguments_summary", {}), ensure_ascii=False),
+                    str(data.get("reason") or "approval required"),
+                    expires_at,
+                    _iso_time(event.time),
+                    event.sequence,
+                ),
+            )
+            return
+        if event.type != "approval/resolved":
+            return
+        approval_id = str(data["approval_id"])
+        expected_revision = int(data.get("expected_revision", 0))
+        changed = connection.execute(
+            """UPDATE approvals
+               SET status=%s, revision=revision+1, actor_json=%s, resolution_reason=%s,
+                   resolved_at=%s, resolved_sequence=%s
+               WHERE id=%s AND session_id=%s AND status='pending' AND revision=%s""",
+            (
+                str(data.get("resolution", "rejected")),
+                json.dumps(data.get("actor", {}), ensure_ascii=False),
+                data.get("reason"),
+                _iso_time(event.time),
+                event.sequence,
+                approval_id,
+                session_id,
+                expected_revision,
+            ),
+        ).rowcount
+        if changed != 1:
+            raise RuntimeStoreError(
+                f"approval {approval_id!r} was resolved concurrently or is missing"
+            )
+
+    def _project_snapshot(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+        durable_cursor: int,
+    ) -> None:
+        """维护不含消息正文的最新运行态快照。
+
+        快照只用于冷启动候选过滤和诊断。恢复命中后仍会重放完整 Event Log,
+        因此投影被删除或损坏不会改变 Session 的业务语义。
+        """
+
+        row = connection.execute(
+            """SELECT snapshot_json FROM session_snapshots
+               WHERE session_id=%s ORDER BY sequence DESC LIMIT 1""",
+            (session_id,),
+        ).fetchone()
+        snapshot: dict[str, Any] = (
+            json.loads(str(row["snapshot_json"]))
+            if row is not None
+            else {
+                "schemaVersion": 1,
+                "activeTurnId": None,
+                "activeStepId": None,
+                "driverState": "idle",
+                "inbox": {"nextTurn": [], "nextStep": []},
+                "hasInboxSplices": False,
+                "pendingApprovalIds": [],
+                "pendingUserInputIds": [],
+                "contextWindowId": None,
+            }
+        )
+        data = dict(event.data)
+        event_type = event.type
+
+        inbox = snapshot.setdefault("inbox", {"nextTurn": [], "nextStep": []})
+        if not isinstance(inbox, dict):
+            inbox = {"nextTurn": [], "nextStep": []}
+            snapshot["inbox"] = inbox
+        if event_type == "agent/inbox/spliced":
+            target = str(data.get("target", ""))
+            key = "nextTurn" if target == "next-turn" else "nextStep"
+            queue = inbox.setdefault(key, [])
+            if not isinstance(queue, list):
+                queue = []
+                inbox[key] = queue
+            index = int(data.get("index", len(queue)))
+            delete_count = int(data.get("delete_count", 0))
+            inserted = data.get("inserted", [])
+            values = (
+                [
+                    {
+                        "inputId": str(item.get("input_id", "")),
+                        "wakeup": bool(item.get("wakeup", True)),
+                    }
+                    for item in inserted
+                    if isinstance(item, Mapping) and item.get("input_id")
+                ]
+                if isinstance(inserted, list)
+                else []
+            )
+            if 0 <= index <= len(queue) and 0 <= delete_count <= len(queue) - index:
+                queue[index : index + delete_count] = values
+            snapshot["hasInboxSplices"] = True
+        elif not bool(snapshot.get("hasInboxSplices")):
+            if event_type == "input/enqueued":
+                target = str(data.get("target", "next-step"))
+                key = "nextTurn" if target == "next-turn" else "nextStep"
+                queue = inbox.setdefault(key, [])
+                if isinstance(queue, list):
+                    queue.append(
+                        {
+                            "inputId": str(data.get("input_id", "")),
+                            "wakeup": bool(data.get("wakeup", True)),
+                        }
+                    )
+            elif event_type in {"input/entered", "input/discarded"}:
+                input_id = str(data.get("input_id", ""))
+                for key in ("nextTurn", "nextStep"):
+                    queue = inbox.get(key)
+                    if isinstance(queue, list):
+                        inbox[key] = [
+                            item
+                            for item in queue
+                            if not isinstance(item, Mapping) or item.get("inputId") != input_id
+                        ]
+
+        if event_type == "turn/start":
+            snapshot["activeTurnId"] = event.turn_id
+            snapshot["driverState"] = "turn_started"
+        elif event_type == "step/start":
+            snapshot["activeStepId"] = event.step_id
+            snapshot["driverState"] = "step_preparing"
+        elif event_type == "request/context":
+            snapshot["driverState"] = "model_streaming"
+        elif event_type == "tool/call":
+            snapshot["driverState"] = "tool_running"
+        elif event_type == "approval/requested":
+            approval_id = str(data.get("approval_id", ""))
+            pending = snapshot.setdefault("pendingApprovalIds", [])
+            if approval_id and isinstance(pending, list) and approval_id not in pending:
+                pending.append(approval_id)
+            snapshot["driverState"] = "approval_waiting"
+        elif event_type == "approval/resolved":
+            approval_id = str(data.get("approval_id", ""))
+            pending = snapshot.get("pendingApprovalIds")
+            if isinstance(pending, list):
+                snapshot["pendingApprovalIds"] = [item for item in pending if item != approval_id]
+            snapshot["driverState"] = "tool_running"
+        elif event_type == "user-input/requested":
+            request_id = str(data.get("request_id", ""))
+            pending = snapshot.setdefault("pendingUserInputIds", [])
+            if request_id and isinstance(pending, list) and request_id not in pending:
+                pending.append(request_id)
+        elif event_type == "user-input/resolved":
+            request_id = str(data.get("request_id", ""))
+            pending = snapshot.get("pendingUserInputIds")
+            if isinstance(pending, list):
+                snapshot["pendingUserInputIds"] = [item for item in pending if item != request_id]
+        elif event_type == "step/end":
+            snapshot["activeStepId"] = None
+            snapshot["driverState"] = "step_completed"
+        elif event_type == "turn/end":
+            if snapshot.get("activeTurnId") == event.turn_id:
+                snapshot["activeTurnId"] = None
+                snapshot["activeStepId"] = None
+            snapshot["driverState"] = "turn_completed"
+        elif event_type == "execution/recovery" and data.get("attention_required"):
+            snapshot["driverState"] = "attention_required"
+        elif event_type == "context/window-started":
+            snapshot["contextWindowId"] = data.get("windowId")
+
+        snapshot["sequence"] = event.sequence
+        snapshot["durableCursor"] = durable_cursor
+        snapshot["lastEventType"] = event_type
+        connection.execute("DELETE FROM session_snapshots WHERE session_id=%s", (session_id,))
+        connection.execute(
+            """INSERT INTO session_snapshots(session_id, sequence, snapshot_json, created_at_ms)
+               VALUES (%s, %s, %s, %s)""",
+            (
+                session_id,
+                event.sequence,
+                json.dumps(snapshot, ensure_ascii=False, separators=(",", ":")),
+                event.time,
+            ),
+        )
+
+    def _project_subagent(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> None:
+        if event.type == "subagent/descriptor":
+            header_row = connection.execute(
+                "SELECT header_json FROM sessions WHERE session_id=%s",
+                (session_id,),
+            ).fetchone()
+            header = json.loads(str(header_row["header_json"])) if header_row is not None else {}
+            payload = {
+                **dict(event.data),
+                "session_id": session_id,
+                "parent_session_id": header.get("parent_session_id"),
+                "status": "ready",
+            }
+        elif event.type in {
+            "subagent/activation-started",
+            "subagent/activation-ended",
+            "subagent/settled",
+            "subagent/ended",
+            "subagent/failed",
+        }:
+            existing = self._projection_payload(connection, session_id, "subagentIdentity")
+            if existing is None:
+                return
+            payload = dict(existing)
+            payload["status"] = str(
+                event.data.get("activity")
+                or event.data.get("status")
+                or event.type.removeprefix("subagent/")
+            )
+        else:
+            return
+        self._upsert_projection(connection, session_id, "subagentIdentity", event.sequence, payload)
+
+    def _project_channel(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> None:
+        if not event.type.startswith("channel/") and event.type != "input/enqueued":
+            return
+        payload = self._projection_payload(connection, session_id, "channelState") or {
+            "bindings": {},
+            "inbounds": {},
+            "turn_routes": {},
+            "pending_deliveries": {},
+            "completed_deliveries": [],
+        }
+        data = dict(event.data)
+        changed = False
+        if event.type in {"channel/bound", "channel/unbound"}:
+            address = _channel_address_key(data)
+            if address is not None:
+                if event.type == "channel/bound":
+                    payload["bindings"][address] = data
+                else:
+                    payload["bindings"].pop(address, None)
+                changed = True
+        elif event.type == "channel/inbound":
+            inbound = _channel_inbound_key(data)
+            if inbound is not None:
+                payload["inbounds"][inbound] = data
+                changed = True
+        elif event.type == "input/enqueued":
+            source = data.get("message_source")
+            if event.turn_id is not None and isinstance(source, Mapping):
+                address = _channel_address_key(source)
+                if address is not None:
+                    payload["turn_routes"][event.turn_id] = dict(source)
+                    changed = True
+        elif event.type == "channel/delivery/queued":
+            delivery_id = str(data.get("delivery_id", ""))
+            if delivery_id:
+                payload["pending_deliveries"][delivery_id] = data
+                changed = True
+        elif event.type in {"channel/delivery/succeeded", "channel/delivery/failed"}:
+            delivery_id = str(data.get("delivery_id", ""))
+            if delivery_id:
+                payload["pending_deliveries"].pop(delivery_id, None)
+                completed = payload["completed_deliveries"]
+                if delivery_id not in completed:
+                    completed.append(delivery_id)
+                changed = True
+        if changed:
+            self._upsert_projection(connection, session_id, "channelState", event.sequence, payload)
+
+    def _project_context(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        event: SessionEvent,
+    ) -> None:
+        row = connection.execute(
+            """SELECT window_id FROM context_window_projection
+               WHERE session_id=%s ORDER BY started_sequence DESC LIMIT 1""",
+            (session_id,),
+        ).fetchone()
+        current_window = str(row["window_id"]) if row is not None else f"legacy-{session_id}"
+        data = dict(event.data)
+        if event.type == "context/window-started":
+            current_window = str(data.get("windowId", current_window))
+            connection.execute(
+                """INSERT INTO context_window_projection(
+                     session_id, window_id, previous_window_id, started_sequence, trigger)
+                   VALUES (%s, %s, %s, %s, %s) ON CONFLICT (session_id, window_id) DO UPDATE SET
+                   previous_window_id=excluded.previous_window_id,
+                   started_sequence=excluded.started_sequence, trigger=excluded.trigger""",
+                (
+                    session_id,
+                    current_window,
+                    data.get("previousWindowId"),
+                    int(data.get("startedSequence", event.sequence)),
+                    str(data.get("trigger", "initial")),
+                ),
+            )
+            connection.execute(
+                """UPDATE context_history_projection SET window_id=%s
+                   WHERE session_id=%s AND window_id=%s""",
+                (current_window, session_id, f"legacy-{session_id}"),
+            )
+            return
+        if event.type == "compaction/checkpoint":
+            next_window = data.get("windowId")
+            carried = data.get("carriedEventSequences")
+            if isinstance(next_window, str) and isinstance(carried, list):
+                for sequence in carried:
+                    if isinstance(sequence, int) and not isinstance(sequence, bool):
+                        connection.execute(
+                            """UPDATE context_history_projection SET window_id=%s
+                               WHERE session_id=%s AND sequence=%s""",
+                            (next_window, session_id, sequence),
+                        )
+            return
+        if event.type in {"context/note-written", "context/note-appended"}:
+            path = str(data.get("path", ""))
+            text = str(data.get("text", ""))
+            existing = connection.execute(
+                "SELECT content FROM context_note_projection WHERE session_id=%s AND path=%s",
+                (session_id, path),
+            ).fetchone()
+            content = (
+                (str(existing["content"]) if existing is not None else "") + text
+                if event.type == "context/note-appended"
+                else text
+            )
+            connection.execute(
+                """INSERT INTO context_note_projection(
+                     session_id, path, content, updated_sequence) VALUES (%s, %s, %s, %s) ON
+                   CONFLICT (session_id, path) DO UPDATE SET content=excluded.content,
+                   updated_sequence=excluded.updated_sequence""",
+                (session_id, path, content, event.sequence),
+            )
+            return
+        history = _context_history_value(event)
+        if history is None:
+            return
+        role, tool_name, content = history
+        connection.execute(
+            """INSERT INTO context_history_projection(
+                 session_id, item_id, window_id, sequence, role, tool_name, content)
+               VALUES (%s, %s, %s, %s, %s, %s, %s) ON CONFLICT (session_id, item_id) DO UPDATE SET
+                   window_id=excluded.window_id, sequence=excluded.sequence, role=excluded.role,
+                   tool_name=excluded.tool_name, content=excluded.content""",
+            (
+                session_id,
+                f"item-{event.sequence}",
+                current_window,
+                event.sequence,
+                role,
+                tool_name,
+                content,
+            ),
+        )
+
+    @staticmethod
+    def _projection_payload(
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        key: str,
+    ) -> dict[str, Any] | None:
+        row = connection.execute(
+            """SELECT payload_json FROM session_projection
+               WHERE session_id=%s AND projection_key=%s""",
+            (session_id, key),
+        ).fetchone()
+        return json.loads(str(row["payload_json"])) if row is not None else None
+
+    @staticmethod
+    def _upsert_projection(
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        key: str,
+        sequence: int,
+        payload: Mapping[str, Any],
+    ) -> None:
+        connection.execute(
+            """INSERT INTO session_projection(
+                 session_id, projection_key, sequence, payload_json) VALUES (%s, %s, %s, %s) ON
+                   CONFLICT (session_id, projection_key) DO UPDATE SET sequence=excluded.sequence,
+                   payload_json=excluded.payload_json""",
+            (session_id, key, sequence, json.dumps(payload, ensure_ascii=False)),
+        )
+
+    def _rebuild_projections_sync(self) -> None:
+        with self._connection() as connection:
+            connection.execute("SELECT pg_advisory_xact_lock(716901, 2)")
+            # 正常 Submission 由 submission/accepted 事实重建。离线迁移生成的
+            # recovery Submission 没有改写旧 Session Log, 因而保留其专用投影行。
+            connection.execute(
+                """DELETE FROM submissions
+                   WHERE operation_id IN (
+                     SELECT payload_json::jsonb->>'operation_id'
+                     FROM session_events WHERE event_type='submission/accepted'
+                   )"""
+            )
+            for table in (
+                "session_projection",
+                "context_window_projection",
+                "context_note_projection",
+                "context_history_projection",
+                "user_input_requests",
+                "approvals",
+                "session_snapshots",
+                "projection_offsets",
+            ):
+                connection.execute(pg_sql.SQL("DELETE FROM {}").format(pg_sql.Identifier(table)))
+            rows = connection.execute(
+                """SELECT events.session_id, events.envelope_json, outbox.cursor
+                   FROM session_events AS events
+                   JOIN event_outbox AS outbox ON outbox.event_id=events.event_id
+                   ORDER BY outbox.cursor"""
+            ).fetchall()
+            for row in rows:
+                self._project_event(
+                    connection,
+                    str(row["session_id"]),
+                    SessionEvent.model_validate_json(str(row["envelope_json"])),
+                    durable_cursor=int(row["cursor"]),
+                )
+            connection.commit()
+
+    def _get_submission_sync(self, operation_id: str) -> Submission | None:
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT * FROM submissions WHERE operation_id=%s", (operation_id,)
+            ).fetchone()
+        return _op_from_row(dict(row)) if row is not None else None
+
+    def _get_receipt_sync(
+        self,
+        operation_id: str,
+        duplicate: bool,
+    ) -> SubmissionReceipt | None:
+        with self._connection() as connection:
+            row = connection.execute(
+                """SELECT submission_id, session_id, accepted_cursor
+                   FROM submissions WHERE operation_id=%s""",
+                (operation_id,),
+            ).fetchone()
+        if row is None:
+            return None
+        return SubmissionReceipt(
+            operationId=operation_id,
+            sessionId=str(row["session_id"]),
+            status=SubmissionStatus.DUPLICATE if duplicate else SubmissionStatus.ACCEPTED,
+            durableCursor=int(row["accepted_cursor"]),
+            submissionId=str(row["submission_id"]),
+        )
+
+    def _claim_next_sync(
+        self,
+        worker_id: str,
+        lease_seconds: float,
+    ) -> ClaimedSubmission | None:
+        with self._connection() as connection:
+            now = _database_now(connection)
+            expires = now + max(1, int(lease_seconds * 1000))
+            row = connection.execute(
+                """SELECT candidate.* FROM submissions AS candidate
+                   WHERE (
+                       candidate.status='pending'
+                       OR (
+                           candidate.status='claimed'
+                           AND candidate.claim_expires_at_ms<=%s
+                       )
+                   )
+                     AND NOT EXISTS (
+                       SELECT 1 FROM submissions AS earlier
+                       WHERE earlier.session_id=candidate.session_id
+                         AND earlier.status IN ('pending', 'claimed')
+                         AND earlier.accepted_sequence<candidate.accepted_sequence
+                     )
+                   ORDER BY candidate.created_at_ms,
+                            candidate.accepted_sequence,
+                            candidate.operation_id
+                   LIMIT 1 FOR UPDATE OF candidate SKIP LOCKED""",
+                (now,),
+            ).fetchone()
+            if row is None:
+                connection.commit()
+                return None
+            connection.execute(
+                """UPDATE submissions
+                   SET status='claimed', claimed_by=%s, claim_expires_at_ms=%s,
+                       attempts=attempts+1, updated_at_ms=%s
+                   WHERE operation_id=%s""",
+                (worker_id, expires, now, row["operation_id"]),
+            )
+            connection.commit()
+            op = _op_from_row(dict(row))
+            return ClaimedSubmission(op, str(row["submission_id"]), int(row["attempts"]) + 1)
+
+    def _release_submission_sync(
+        self,
+        operation_id: str,
+        error: str | None,
+    ) -> None:
+        with self._connection() as connection:
+            changed = connection.execute(
+                """UPDATE submissions SET status='pending', claimed_by=NULL,
+                   claim_expires_at_ms=NULL, last_error=%s, updated_at_ms=%s
+                   WHERE operation_id=%s AND status='claimed'""",
+                (error, _now_ms(), operation_id),
+            ).rowcount
+            connection.commit()
+        if not changed:
+            raise KeyError(f"unknown submission: {operation_id}")
+
+    def _pending_sync(self, session_id: str | None) -> tuple[Submission, ...]:
+        sql = "SELECT * FROM submissions WHERE status IN ('pending', 'claimed')"
+        values: tuple[Any, ...] = ()
+        if session_id is not None:
+            sql += " AND session_id=%s"
+            values = (session_id,)
+        sql += " ORDER BY created_at_ms, accepted_sequence, operation_id"
+        with self._connection() as connection:
+            rows = connection.execute(pg_sql.SQL(sql), values).fetchall()
+        return tuple(_op_from_row(dict(row)) for row in rows)
+
+    def _unfinished_counts_sync(self, session_id: str) -> tuple[int, int]:
+        with self._connection() as connection:
+            row = connection.execute(
+                """SELECT
+                     COUNT(*) AS op_count,
+                     SUM(CASE WHEN kind='user-input' THEN 1 ELSE 0 END) AS turn_count
+                   FROM submissions
+                   WHERE session_id=%s AND status IN ('pending', 'claimed')""",
+                (session_id,),
+            ).fetchone()
+        assert row is not None
+        return int(row["op_count"]), int(row["turn_count"] or 0)
+
+    def _acquire_sync(
+        self,
+        session_id: str,
+        owner_id: str,
+        ttl_seconds: float,
+    ) -> SessionLease | None:
+        with self._connection() as connection:
+            parent = connection.execute(
+                "SELECT session_id FROM sessions WHERE session_id=%s FOR UPDATE", (session_id,)
+            ).fetchone()
+            if parent is None:
+                raise KeyError(f"unknown session: {session_id}")
+            now = _database_now(connection)
+            expires = now + max(1, int(ttl_seconds * 1000))
+            row = connection.execute(
+                "SELECT owner_id, generation, expires_at_ms FROM session_leases WHERE "
+                "session_id=%s FOR UPDATE",
+                (session_id,),
+            ).fetchone()
+            if row is not None and int(row["expires_at_ms"]) > now and row["owner_id"] != owner_id:
+                connection.commit()
+                return None
+            # 同一 Worker 在 Lease 尚有效时重复 acquire 只是续期，不能提升
+            # generation；否则它会让自己仍在运行的 Active Turn 立刻变成旧写入方。
+            same_live_owner = (
+                row is not None
+                and str(row["owner_id"]) == owner_id
+                and int(row["expires_at_ms"]) > now
+            )
+            if same_live_owner:
+                assert row is not None
+                generation = int(row["generation"])
+            else:
+                generation = (int(row["generation"]) if row is not None else 0) + 1
+            connection.execute(
+                """INSERT INTO session_leases(
+                     session_id, owner_id, generation, expires_at_ms, updated_at_ms)
+                   VALUES (%s, %s, %s, %s, %s)
+                   ON CONFLICT(session_id) DO UPDATE SET
+                     owner_id=excluded.owner_id,
+                     generation=excluded.generation,
+                     expires_at_ms=excluded.expires_at_ms,
+                     updated_at_ms=excluded.updated_at_ms""",
+                (session_id, owner_id, generation, expires, now),
+            )
+            connection.commit()
+        return SessionLease(session_id, owner_id, generation, expires)
+
+    def _renew_sync(self, lease: SessionLease, ttl_seconds: float) -> SessionLease:
+        with self._connection() as connection:
+            connection.execute(
+                "SELECT generation FROM session_leases WHERE session_id=%s FOR UPDATE",
+                (lease.session_id,),
+            )
+            now = _database_now(connection)
+            expires = now + max(1, int(ttl_seconds * 1000))
+            changed = connection.execute(
+                """UPDATE session_leases SET expires_at_ms=%s, updated_at_ms=%s
+                   WHERE session_id=%s AND owner_id=%s AND generation=%s AND expires_at_ms>%s""",
+                (
+                    expires,
+                    now,
+                    lease.session_id,
+                    lease.owner_id,
+                    lease.generation,
+                    now,
+                ),
+            ).rowcount
+            connection.commit()
+        if not changed:
+            raise FencingTokenRejected(f"lease {lease.session_id!r} is no longer current")
+        return SessionLease(lease.session_id, lease.owner_id, lease.generation, expires)
+
+    def _release_lease_sync(self, lease: SessionLease) -> None:
+        with self._connection() as connection:
+            connection.execute(
+                """UPDATE session_leases SET expires_at_ms=0
+                   WHERE session_id=%s AND owner_id=%s AND generation=%s""",
+                (lease.session_id, lease.owner_id, lease.generation),
+            )
+            connection.commit()
+
+    def _check_fencing(
+        self,
+        connection: psycopg.Connection[dict[str, Any]],
+        session_id: str,
+        token: int,
+    ) -> None:
+        row = connection.execute(
+            "SELECT generation, expires_at_ms FROM session_leases WHERE session_id=%s FOR UPDATE",
+            (session_id,),
+        ).fetchone()
+        if (
+            row is None
+            or int(row["generation"]) != token
+            or int(row["expires_at_ms"]) <= _database_now(connection)
+        ):
+            raise FencingTokenRejected(f"fencing token {token} is stale for {session_id!r}")
+
+    def _read_outbox_sync(
+        self,
+        after_cursor: int,
+        limit: int,
+    ) -> tuple[CommittedSessionEvent, ...]:
+        with self._connection() as connection:
+            rows = connection.execute(
+                """SELECT * FROM event_outbox WHERE cursor>%s
+                   ORDER BY cursor LIMIT %s""",
+                (after_cursor, limit),
+            ).fetchall()
+        return tuple(
+            CommittedSessionEvent(
+                eventId=str(row["event_id"]),
+                sessionId=str(row["session_id"]),
+                sequence=int(row["sequence"]),
+                eventType=str(row["event_type"]),
+                payload=json.loads(str(row["payload_json"])),
+                recordedAtMs=int(row["recorded_at_ms"]),
+                durableCursor=int(row["cursor"]),
+            )
+            for row in rows
+        )
+
+    def _latest_outbox_cursor_sync(self) -> int:
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT COALESCE(MAX(cursor), 0) AS cursor FROM event_outbox"
+            ).fetchone()
+        return int(row["cursor"]) if row is not None else 0
+
+
+def _op_from_row(row: Mapping[str, Any]) -> Submission:
+    return Submission.model_validate(
+        {
+            "operationId": row["operation_id"],
+            "sessionId": row["session_id"],
+            "kind": row["kind"],
+            "payload": json.loads(str(row["payload_json"])),
+            "expectedRevision": row["expected_revision"],
+            "source": json.loads(str(row["source_json"])),
+        }
+    )
+
+
+def _event_from_json(session_id: str, value: str) -> SessionEvent:
+    """恢复线协议事件, 并重新附加不参与持久化的 Session 所有权。"""
+
+    return SessionEvent.model_validate_json(value).model_copy(update={"session_id": session_id})
+
+
+def _public_user_input(row: Mapping[str, Any]) -> dict[str, Any]:
+    raw_value = row.get("value_json")
+    raw_actor = row.get("actor_json")
+    return {
+        "requestId": str(row["request_id"]),
+        "sessionId": str(row["session_id"]),
+        "turnId": str(row.get("turn_id") or ""),
+        "prompt": str(row.get("prompt") or ""),
+        "inputSchema": json.loads(str(row.get("input_schema_json") or "{}")),
+        "status": str(row.get("status") or "pending"),
+        "outcome": str(row["outcome"]) if row.get("outcome") is not None else None,
+        "value": json.loads(str(raw_value)) if raw_value is not None else None,
+        "actor": json.loads(str(raw_actor)) if raw_actor is not None else {},
+        "reason": row.get("resolution_reason"),
+        "revision": int(row.get("revision") or 0),
+        "expiresAtMs": int(row.get("expires_at_ms") or 0),
+    }
+
+
+def _public_approval(row: Mapping[str, Any]) -> dict[str, Any]:
+    """把内部审批投影转换为 Runtime Plane 的稳定公共字段。"""
+
+    raw_actor = row.get("actor_json")
+    try:
+        actor = json.loads(str(raw_actor or "{}"))
+    except json.JSONDecodeError:
+        actor = {}
+    return {
+        "approvalId": str(row["id"]),
+        "sessionId": str(row.get("session_id") or ""),
+        "turnId": str(row.get("turn_id") or ""),
+        "stepId": str(row.get("step_id") or ""),
+        "callId": str(row.get("tool_call_id") or ""),
+        "operationId": str(row.get("operation_id") or ""),
+        "toolName": str(row.get("tool_name") or ""),
+        "argumentsSummary": json.loads(str(row.get("arguments_json") or "{}")),
+        "reason": str(row.get("reason") or ""),
+        "outcome": str(row.get("status") or "pending"),
+        "revision": int(row.get("revision") or 0),
+        "expiresAt": row.get("expires_at"),
+        "actor": actor,
+        "resolutionReason": row.get("resolution_reason"),
+        "createdAt": row.get("created_at"),
+        "resolvedAt": row.get("resolved_at"),
+    }
+
+
+def _iso_time(time_ms: int) -> str:
+    return datetime.fromtimestamp(time_ms / 1000, UTC).isoformat()
+
+
+def _event_id(session_id: str, sequence: int) -> str:
+    return uuid5(NAMESPACE_URL, f"qi-pi:{session_id}:{sequence}").hex
+
+
+def _now_ms() -> int:
+    return time.time_ns() // 1_000_000
+
+
+def _channel_address_key(value: Mapping[str, Any]) -> str | None:
+    channel_id = value.get("channel_id", value.get("channelId"))
+    account_id = value.get("account_id", value.get("accountId"))
+    conversation_id = value.get("conversation_id", value.get("conversationId"))
+    if not channel_id or not account_id or not conversation_id:
+        return None
+    return json.dumps(
+        [str(channel_id), str(account_id), str(conversation_id)],
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+
+
+def _channel_inbound_key(value: Mapping[str, Any]) -> str | None:
+    address = _channel_address_key(value)
+    message_id = value.get("message_id", value.get("messageId"))
+    if address is None or not message_id:
+        return None
+    return f"{address}:{json.dumps(str(message_id), ensure_ascii=False)}"
+
+
+def _context_history_value(event: SessionEvent) -> tuple[str, str | None, str] | None:
+    if event.type == "user/message":
+        return "user", None, _json_text(event.data)
+    if event.type == "assistant/message":
+        return "assistant", None, _json_text(event.data.get("message"))
+    if event.type == "tool/call":
+        return "tool", str(event.data.get("name", "")) or None, str(event.data.get("arguments", ""))
+    if event.type == "tool/result":
+        return "tool", None, _json_text(event.data.get("message"))
+    return None
+
+
+def _json_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, Mapping):
+        return "\n".join(
+            _json_text(item)
+            for key, item in value.items()
+            if key in {"content", "text", "name", "arguments", "message"}
+        )
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return "\n".join(_json_text(item) for item in value)
+    return ""
+
+
+__all__ = [
+    "RUNTIME_STORE_SCHEMA",
+    "FencingTokenRejected",
+    "PostgresRuntimeStore",
+    "RuntimeStoreError",
+    "SequenceConflict",
+]
+
+
+def _database_now(connection: psycopg.Connection[dict[str, Any]]) -> int:
+    row = connection.execute(
+        "SELECT (extract(epoch FROM clock_timestamp()) * 1000)::bigint AS now_ms"
+    ).fetchone()
+    assert row is not None
+    return int(row["now_ms"])