agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/sessions/invocation_identity.py

@@ -0,0 +1,235 @@
+"""Trusted business-identity binding for canonical KsADK sessions.
+
+The public ``UserId`` field remains a compatibility hint.  Hosted callers are
+authorized by a verified four-part business identity, which is converted to an
+opaque native user key and durably bound to the session before transcript
+access.  This prevents a known ``SessionId`` from becoming an authorization
+credential while still allowing an authorized legacy session to be adopted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from fastapi import HTTPException
+
+from ksadk.runtime_context import PlatformIdentityContext
+from ksadk.sessions.base import BaseSessionService, Session
+
+SESSION_IDENTITY_SCOPE = "platform_identity"
+SESSION_IDENTITY_BINDING_VERSION = 1
+DEFAULT_IAM_IDENTITY_NAMESPACE = "kscloud-iam"
+
+
+def coerce_platform_identity(value: Any) -> PlatformIdentityContext:
+    if isinstance(value, PlatformIdentityContext):
+        return value
+    return PlatformIdentityContext.from_payload(value if isinstance(value, Mapping) else None)
+
+
+def require_complete_platform_identity(value: Any) -> PlatformIdentityContext:
+    identity = coerce_platform_identity(value)
+    if identity.is_empty:
+        return identity
+    if not identity.is_complete:
+        raise HTTPException(status_code=401, detail="Incomplete trusted business identity context")
+    return identity
+
+
+def identity_owner_payload(value: Any) -> dict[str, str]:
+    identity = require_complete_platform_identity(value)
+    if identity.is_empty:
+        return {}
+    return {
+        "identity_namespace": identity.identity_namespace,
+        "tenant_id": identity.tenant_id,
+        "subject_type": identity.subject_type,
+        "subject_id": identity.subject_id,
+    }
+
+
+def identity_digest(value: Any) -> str:
+    owner = identity_owner_payload(value)
+    if not owner:
+        return ""
+    canonical = json.dumps(owner, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def identity_native_user_id(value: Any) -> str:
+    """Return an opaque collision-resistant native storage user key."""
+
+    digest = identity_digest(value)
+    return f"aeu_{digest}" if digest else ""
+
+
+def identity_scope_ref(value: Any) -> str:
+    digest = identity_digest(value)
+    return f"aei_{digest}" if digest else ""
+
+
+def identity_session_is_legacy(value: Any, session_user_id: str) -> bool:
+    """Return whether an authorized canonical row still uses its legacy user key."""
+
+    identity = require_complete_platform_identity(value)
+    return bool(
+        not identity.is_empty
+        and session_user_id
+        and session_user_id != identity_native_user_id(identity)
+    )
+
+
+def identity_can_adopt_any_legacy_user(value: Any) -> bool:
+    """Whether this verified principal owns the whole legacy Agent runtime."""
+
+    identity = require_complete_platform_identity(value)
+    return bool(
+        not identity.is_empty
+        and identity.identity_namespace == DEFAULT_IAM_IDENTITY_NAMESPACE
+        and identity.subject_type == "account"
+    )
+
+
+def identity_can_adopt_legacy_user(value: Any, legacy_user_id: str) -> bool:
+    """Whether a verified IAM principal deterministically owns a legacy user."""
+
+    identity = require_complete_platform_identity(value)
+    # ``aeu_`` is reserved for identity-aware rows. If a concurrent creator
+    # has written the opaque key but has not persisted its binding yet, no
+    # other principal may mistake that row for legacy data and claim it.
+    if str(legacy_user_id or "").startswith("aeu_"):
+        return False
+    if identity_can_adopt_any_legacy_user(identity):
+        return True
+    return bool(
+        not identity.is_empty
+        and identity.identity_namespace == DEFAULT_IAM_IDENTITY_NAMESPACE
+        and identity.subject_type == "user"
+        and str(legacy_user_id or "") == identity.subject_id
+    )
+
+
+def _binding_payload(identity: PlatformIdentityContext, native_user_id: str) -> dict[str, Any]:
+    return {
+        "version": SESSION_IDENTITY_BINDING_VERSION,
+        "owner": identity_owner_payload(identity),
+        "scope_ref": identity_scope_ref(identity),
+        "native_user_id": native_user_id,
+    }
+
+
+async def _read_binding(
+    service: BaseSessionService,
+    session: Session,
+) -> dict[str, Any]:
+    state = await service.get_state(
+        agent_id=session.agent_id,
+        user_id=session.user_id,
+        session_id=session.id,
+        scope=SESSION_IDENTITY_SCOPE,
+    )
+    return dict(state.state) if state is not None else {}
+
+
+async def session_identity_binding_matches(
+    *,
+    service: BaseSessionService,
+    session: Session,
+    identity: Any,
+) -> bool:
+    resolved = require_complete_platform_identity(identity)
+    if resolved.is_empty:
+        return False
+    binding = await _read_binding(service, session)
+    return bool(binding and _binding_matches(binding, resolved, session_user_id=session.user_id))
+
+
+def _binding_matches(
+    binding: Mapping[str, Any],
+    identity: PlatformIdentityContext,
+    *,
+    session_user_id: str,
+) -> bool:
+    return (
+        dict(binding.get("owner") or {}) == identity_owner_payload(identity)
+        and str(binding.get("scope_ref") or "") == identity_scope_ref(identity)
+        and str(binding.get("native_user_id") or "") == session_user_id
+    )
+
+
+def _ownership_conflict() -> HTTPException:
+    # Do not reveal which principal owns a guessed session id.
+    return HTTPException(status_code=404, detail="Session not found")
+
+
+async def bind_or_validate_session_identity(
+    *,
+    service: BaseSessionService,
+    session: Session,
+    identity: Any,
+    requested_user_id: str,
+) -> Session:
+    """Validate an existing session or durably adopt an authorized legacy row."""
+
+    resolved = require_complete_platform_identity(identity)
+    if resolved.is_empty:
+        # Legacy/local callers historically resume with SessionId alone. Keep
+        # that behavior when no trusted identity exists, while an explicitly
+        # supplied UserId must still match. Hosted traffic receives a verified
+        # default IAM identity and therefore never relies on this fallback.
+        if requested_user_id and session.user_id != requested_user_id:
+            raise HTTPException(
+                status_code=409,
+                detail="Session id belongs to a different agent or user",
+            )
+        return session
+
+    binding = await _read_binding(service, session)
+    if binding:
+        if not _binding_matches(binding, resolved, session_user_id=session.user_id):
+            raise _ownership_conflict()
+        return session
+
+    expected_native_user_id = identity_native_user_id(resolved)
+    # A newly-created identity-aware row already carries the opaque user key.
+    # Legacy adoption is intentionally limited to the built-in IAM mapping:
+    # an account principal owns the historical Agent runtime, while an IAM
+    # user may only recover the row whose old UserId equals its verified
+    # subject. Customer-defined tenants must use a controlled migration; a
+    # caller-supplied UserId can never make the first visitor the owner.
+    if session.user_id != expected_native_user_id:
+        if not identity_can_adopt_legacy_user(resolved, session.user_id):
+            raise _ownership_conflict()
+
+    await service.update_state(
+        agent_id=session.agent_id,
+        user_id=session.user_id,
+        session_id=session.id,
+        scope=SESSION_IDENTITY_SCOPE,
+        state_delta=_binding_payload(resolved, session.user_id),
+    )
+    # Re-read after the write.  Backends serialize individual state updates;
+    # this also fails closed if a competing claimant replaced the binding.
+    persisted = await _read_binding(service, session)
+    if not _binding_matches(persisted, resolved, session_user_id=session.user_id):
+        raise _ownership_conflict()
+    return session
+
+
+__all__ = [
+    "SESSION_IDENTITY_SCOPE",
+    "bind_or_validate_session_identity",
+    "coerce_platform_identity",
+    "identity_digest",
+    "identity_can_adopt_any_legacy_user",
+    "identity_can_adopt_legacy_user",
+    "identity_native_user_id",
+    "identity_owner_payload",
+    "identity_session_is_legacy",
+    "identity_scope_ref",
+    "require_complete_platform_identity",
+    "session_identity_binding_matches",
+]

ksadk/sessions/local_service.py

@@ -6,6 +6,8 @@ import asyncio
 import json
 import os
 import sqlite3
+import threading
+import time
 from collections.abc import AsyncIterator, Iterator
 from contextlib import closing, contextmanager
 from pathlib import Path
@@ -20,6 +22,7 @@ from ksadk.sessions._local_tables import (
     LEGACY_EVENTS_TABLE,
     LEGACY_SESSIONS_TABLE,
     LEGACY_STATES_TABLE,
+    tool_receipts_table,
 )
 from ksadk.sessions.base import (
     CANONICAL_EVENT_STORAGE_CAPABILITIES,
@@ -29,6 +32,13 @@ from ksadk.sessions.base import (
     SessionEvent,
     SessionEventQuery,
     SessionState,
+    ToolReceiptClaim,
+)
+from ksadk.sessions.db_budget import session_db_budget
+from ksadk.sessions.errors import (
+    CheckpointLookupTimeout,
+    HistoryProjectionBudgetExceeded,
+    SessionBackendUnavailable,
 )
 
 
@@ -56,6 +66,150 @@ def resolve_local_session_path(project_dir: Optional[str] = None) -> Path:
 class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
     storage_capabilities = CANONICAL_EVENT_STORAGE_CAPABILITIES
 
+    def _resume_related_pages_sync(
+        self, session_id: str, page_size: int,
+        cancelled: threading.Event,
+        active_connection: list[sqlite3.Connection | None],
+        expected_session: Session | None,
+    ) -> list[list[SessionEvent]]:
+        pages: list[list[SessionEvent]] = []
+        event_types = ("run_checkpoint", "run_resume", "runtime_resume", "continuation.created", "continuation.resumed")
+        with self._connection() as connection:
+            active_connection[0] = connection
+            budget = session_db_budget()
+            deadline = time.monotonic() + budget.write_operation_seconds
+            # SQLite interrupt() cannot stop a busy-lock wait. Keep each wait
+            # shorter than the cancellation cleanup window.
+            busy_ms = max(1, int(1000 * min(
+                budget.lock_seconds, budget.cleanup_seconds,
+                max(0.001, deadline - time.monotonic()),
+            )))
+            connection.execute(f"PRAGMA busy_timeout = {busy_ms}")
+            connection.set_progress_handler(
+                lambda: int(cancelled.is_set() or time.monotonic() >= deadline), 1000
+            )
+            try:
+                connection.execute("BEGIN")
+            except sqlite3.OperationalError as exc:
+                if "locked" in str(exc).lower() or "interrupted" in str(exc).lower():
+                    raise CheckpointLookupTimeout("Checkpoint lookup deadline exceeded") from exc
+                raise
+            if expected_session is not None:
+                from ksadk.sessions.errors import HistoryReloadRequired
+
+                owner = connection.execute(
+                    f"SELECT agent_id,user_id,created_at FROM {KSADK_SESSIONS_TABLE} WHERE id=?",
+                    (session_id,),
+                ).fetchone()
+                if (owner is None or owner["agent_id"] != expected_session.agent_id
+                        or owner["user_id"] != expected_session.user_id
+                        or float(owner["created_at"]) != expected_session.created_at):
+                    raise HistoryReloadRequired("Checkpoint session changed during lookup")
+            upper = int(connection.execute(
+                f"SELECT COALESCE(MAX(seq_id),0) FROM {KSADK_EVENTS_TABLE} WHERE session_id=?",
+                (session_id,),
+            ).fetchone()[0])
+            count = int(connection.execute(
+                f"SELECT COUNT(*) FROM {KSADK_EVENTS_TABLE} WHERE session_id=? "
+                "AND event_type IN (?,?,?,?,?) AND seq_id<=?",
+                (session_id, *event_types, upper),
+            ).fetchone()[0])
+            if count > 8192:
+                raise HistoryProjectionBudgetExceeded(
+                    "Checkpoint lookup exceeds 8192 related events"
+                )
+            cursor = 0
+            used = 0
+            while True:
+                if cancelled.is_set() or time.monotonic() >= deadline:
+                    raise CheckpointLookupTimeout("Checkpoint lookup deadline exceeded")
+                candidate = (
+                    f"FROM {KSADK_EVENTS_TABLE} WHERE session_id=? "
+                    "AND event_type IN (?,?,?,?,?) AND seq_id>? AND seq_id<=? "
+                    "ORDER BY seq_id,id LIMIT ?"
+                )
+                params = (session_id, *event_types, cursor, upper, page_size)
+                size = int(connection.execute(
+                    "SELECT COALESCE(SUM(LENGTH(CAST(content_json AS BLOB))+"
+                    "LENGTH(CAST(state_delta_json AS BLOB))+"
+                    "LENGTH(CAST(metadata_json AS BLOB))+"
+                    "LENGTH(CAST(json_quote(id) AS BLOB))+"
+                    "LENGTH(CAST(json_quote(session_id) AS BLOB))+"
+                    "LENGTH(CAST(json_quote(author) AS BLOB))+"
+                    "LENGTH(CAST(json_quote(event_type) AS BLOB))+"
+                    "LENGTH(CAST(json_quote(invocation_id) AS BLOB))+256),0) "
+                    "FROM (SELECT id,session_id,author,event_type,invocation_id,"
+                    "content_json,state_delta_json,metadata_json "
+                    + candidate + ")", params,
+                ).fetchone()[0])
+                if used + size > 16 * 1024 * 1024:
+                    raise HistoryProjectionBudgetExceeded(
+                        "Checkpoint lookup exceeds 16 MiB of related events"
+                    )
+                rows = connection.execute(
+                    "SELECT id,session_id,author,event_type,content_json,timestamp,"
+                    "state_delta_json,seq_id,invocation_id,metadata_json "
+                    + candidate, params,
+                ).fetchall()
+                if not rows:
+                    break
+                pages.append([self._event_from_query_row(row) for row in rows])
+                used += size
+                cursor = int(rows[-1]["seq_id"])
+                if len(rows) < page_size:
+                    break
+        active_connection[0] = None
+        return pages
+
+    async def iter_resume_related_event_pages(
+        self, session_id: str, *, page_size: int = 256,
+        expected_session: Session | None = None,
+    ) -> AsyncIterator[list[SessionEvent]]:
+        async with self._lock:
+            cancelled = threading.Event()
+            active_connection: list[sqlite3.Connection | None] = [None]
+            task = asyncio.create_task(asyncio.to_thread(
+                self._resume_related_pages_sync, session_id, page_size,
+                cancelled, active_connection, expected_session,
+            ))
+            try:
+                pages = await asyncio.shield(task)
+            except sqlite3.OperationalError as exc:
+                if "locked" in str(exc).lower() or "interrupted" in str(exc).lower():
+                    raise CheckpointLookupTimeout("Checkpoint lookup deadline exceeded") from exc
+                raise
+            except asyncio.CancelledError:
+                cancelled.set()
+                if active_connection[0] is not None:
+                    try:
+                        active_connection[0].interrupt()
+                    except sqlite3.ProgrammingError:
+                        pass  # Worker closed its connection during cancellation.
+                # Join the interrupted SQLite worker before releasing _lock.
+                try:
+                    await asyncio.wait_for(asyncio.shield(task), timeout=1.0)
+                except (Exception, asyncio.CancelledError):
+                    pass
+                if not task.done():
+                    task.add_done_callback(
+                        lambda done: done.exception() if not done.cancelled() else None
+                    )
+                raise
+        for page in pages:
+            yield page
+
+    async def get_session_ids_by_ids(
+        self, session_ids: list[str], agent_id: str | None = None
+    ) -> list[str]:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._get_session_ids_by_ids_sync, session_ids, agent_id
+            )
+
+    async def list_session_ids(self, agent_id: str | None = None) -> list[str]:
+        async with self._lock:
+            return await asyncio.to_thread(self._list_session_ids_sync, agent_id)
+
     def __init__(self, db_path: Optional[Path] = None, *, project_dir: Optional[str] = None):
         self.db_path = (
             Path(db_path).expanduser().resolve()
@@ -81,6 +235,26 @@ class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
         async with self._lock:
             return await asyncio.to_thread(self._get_session_sync, session_id)
 
+    async def get_adk_session_snapshot(
+        self, session_id: str, expected_session: Session | None = None
+    ) -> Optional[Session]:
+        def read() -> Optional[Session]:
+            with self._connection() as connection:
+                connection.execute("BEGIN")
+                session = self._get_session_sync(session_id, connection=connection)
+                if expected_session is not None and (
+                    session is None or session.agent_id != expected_session.agent_id
+                    or session.user_id != expected_session.user_id
+                    or session.created_at != expected_session.created_at
+                ):
+                    from ksadk.sessions.errors import HistoryReloadRequired
+
+                    raise HistoryReloadRequired("Session changed during legacy read")
+                return session
+
+        async with self._lock:
+            return await asyncio.to_thread(read)
+
     async def get_session_metadata(self, session_id: str) -> Optional[Session]:
         async with self._lock:
             return await asyncio.to_thread(
@@ -89,6 +263,71 @@ class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
                 include_events=False,
             )
 
+    async def get_session_header(self, session_id: str) -> Optional[Session]:
+        def read_header() -> Optional[Session]:
+            with self._connection() as connection:
+                row = connection.execute(
+                    f"SELECT id,agent_id,user_id,title,title_source,summary,"
+                    f"first_prompt,last_prompt,created_at,updated_at,version "
+                    f"FROM {KSADK_SESSIONS_TABLE} WHERE id=?",
+                    (session_id,),
+                ).fetchone()
+            if row is None:
+                return None
+            return Session(
+                id=row["id"], agent_id=row["agent_id"], user_id=row["user_id"],
+                title=row["title"], title_source=row["title_source"],
+                summary=row["summary"], first_prompt=row["first_prompt"],
+                last_prompt=row["last_prompt"], created_at=row["created_at"],
+                updated_at=row["updated_at"], version=row["version"],
+            )
+
+        async with self._lock:
+            return await asyncio.to_thread(read_header)
+
+    async def ensure_session_header(
+        self, agent_id: str, user_id: str, session_id: str
+    ) -> Session:
+        def ensure() -> Session:
+            now = time.time()
+            with self._connection() as connection:
+                inserted = connection.execute(
+                    f"INSERT OR IGNORE INTO {KSADK_SESSIONS_TABLE} ("
+                    "id,agent_id,user_id,title,title_source,summary,first_prompt,"
+                    "last_prompt,state_json,created_at,updated_at,version) "
+                    "VALUES (?,?,?,'','','','','','{}',?,?,0)",
+                    (session_id, agent_id, user_id, now, now),
+                ).rowcount
+                row = connection.execute(
+                    f"SELECT id,agent_id,user_id,title,title_source,summary,"
+                    f"first_prompt,last_prompt,created_at,updated_at,version "
+                    f"FROM {KSADK_SESSIONS_TABLE} WHERE id=?",
+                    (session_id,),
+                ).fetchone()
+                if row is None:
+                    raise RuntimeError("Canonical AG-UI session creation was not visible")
+                if inserted:
+                    connection.execute(
+                        f"INSERT OR IGNORE INTO {KSADK_STATES_TABLE} ("
+                        "scope,agent_id,user_id,session_id,state_json,version,updated_at) "
+                        "VALUES ('session',?,?,?,'{}',0,?)",
+                        (row["agent_id"], row["user_id"], session_id, now),
+                    )
+            return Session(
+                id=row["id"], agent_id=row["agent_id"], user_id=row["user_id"],
+                title=row["title"], title_source=row["title_source"],
+                summary=row["summary"], first_prompt=row["first_prompt"],
+                last_prompt=row["last_prompt"], created_at=row["created_at"],
+                updated_at=row["updated_at"], version=row["version"],
+            )
+
+        async with self._lock:
+            return await asyncio.to_thread(ensure)
+
+    async def get_session_summary_events(self, session_id: str) -> list[SessionEvent]:
+        async with self._lock:
+            return await asyncio.to_thread(self._get_session_summary_events_sync, session_id)
+
     async def list_sessions(
         self,
         agent_id: str,
@@ -142,10 +381,67 @@ class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
         async with self._lock:
             return await asyncio.to_thread(self._append_event_sync, session_id, event)
 
+    async def append_event_if_session_matches(
+        self, session_id: str, event: SessionEvent, expected_session: Session
+    ) -> SessionEvent:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._append_event_sync, session_id, event, expected_session
+            )
+
+    async def claim_tool_receipt(self, session_id: str, **kwargs) -> ToolReceiptClaim:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._claim_tool_receipt_sync, session_id, **kwargs
+            )
+
+    async def settle_tool_receipt(self, session_id: str, **kwargs) -> ToolReceiptClaim:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._settle_tool_receipt_sync, session_id, **kwargs
+            )
+
+    async def get_tool_receipt_claim(
+        self, session_id: str, *, idempotency_key: str
+    ) -> ToolReceiptClaim | None:
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._get_tool_receipt_claim_sync,
+                session_id,
+                idempotency_key=idempotency_key,
+            )
+
     async def get_event_by_id(self, session_id: str, event_id: str) -> Optional[SessionEvent]:
         async with self._lock:
             return await asyncio.to_thread(self._get_event_by_id_sync, session_id, event_id)
 
+    async def get_event_by_id_if_session_matches(
+        self, session_id: str, event_id: str, expected_session: Session
+    ) -> Optional[SessionEvent]:
+        def read() -> Optional[SessionEvent]:
+            with self._connection() as connection:
+                connection.execute("BEGIN")
+                owner = connection.execute(
+                    f"SELECT agent_id,user_id,created_at FROM {KSADK_SESSIONS_TABLE} "
+                    "WHERE id=?", (session_id,),
+                ).fetchone()
+                if (owner is None or owner["agent_id"] != expected_session.agent_id
+                        or owner["user_id"] != expected_session.user_id
+                        or float(owner["created_at"]) != expected_session.created_at):
+                    from ksadk.sessions.errors import HistoryReloadRequired
+
+                    raise HistoryReloadRequired("Session changed during legacy import")
+                row = connection.execute(
+                    f"SELECT id,session_id,author,event_type,content_json,timestamp,"
+                    f"state_delta_json,seq_id,invocation_id,metadata_json "
+                    f"FROM {KSADK_EVENTS_TABLE} WHERE session_id=? AND id=?",
+                    (session_id, event_id),
+                ).fetchone()
+                return self._event_from_query_row(row) if row is not None else None
+
+        async with self._lock:
+            return await asyncio.to_thread(read)
+
     async def get_events_by_invocation_id(
         self,
         session_id: str,
@@ -569,8 +865,21 @@ class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
                     version INTEGER NOT NULL DEFAULT 0,
                     updated_at REAL NOT NULL,
                     PRIMARY KEY (scope, agent_id, user_id, session_id)
+                    );
+
+                CREATE TABLE IF NOT EXISTS {tool_receipts_table} (
+                    session_id TEXT NOT NULL,
+                    idempotency_key TEXT NOT NULL,
+                    tool_name TEXT NOT NULL,
+                    arguments_digest TEXT NOT NULL,
+                    state TEXT NOT NULL CHECK (state IN ('unknown', 'completed', 'failed')),
+                    claim_id TEXT NOT NULL,
+                    output_json TEXT,
+                    PRIMARY KEY (session_id, idempotency_key),
+                    FOREIGN KEY(session_id) REFERENCES {KSADK_SESSIONS_TABLE}(id) ON DELETE CASCADE
                 );
                 """)
+            self._validate_tool_receipt_schema(connection)
             self._ensure_columns(
                 connection,
                 KSADK_SESSIONS_TABLE,
@@ -604,6 +913,42 @@ class LocalSessionService(_LocalServiceSyncMixin, BaseSessionService):
             self._ensure_event_seq_unique_index(connection)
             connection.commit()
 
+    @staticmethod
+    def _validate_tool_receipt_schema(connection: sqlite3.Connection) -> None:
+        columns = connection.execute(
+            f"PRAGMA table_info({tool_receipts_table})"
+        ).fetchall()
+        required = {
+            "session_id",
+            "idempotency_key",
+            "tool_name",
+            "arguments_digest",
+            "state",
+            "claim_id",
+            "output_json",
+        }
+        if {str(row["name"]) for row in columns} != required:
+            raise RuntimeError("tool receipt schema is incomplete")
+        primary_key = [str(row["name"]) for row in columns if int(row["pk"] or 0)]
+        if primary_key != ["session_id", "idempotency_key"]:
+            raise RuntimeError("tool receipt schema primary key is invalid")
+        foreign_keys = connection.execute(
+            f"PRAGMA foreign_key_list({tool_receipts_table})"
+        ).fetchall()
+        if not any(
+            str(row["table"]) == KSADK_SESSIONS_TABLE
+            and str(row["on_delete"]).upper() == "CASCADE"
+            for row in foreign_keys
+        ):
+            raise RuntimeError("tool receipt schema foreign key is invalid")
+        schema_row = connection.execute(
+            "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
+            (tool_receipts_table,),
+        ).fetchone()
+        schema_sql = str(schema_row["sql"] if schema_row else "").lower()
+        if "check" not in schema_sql or "unknown" not in schema_sql:
+            raise RuntimeError("tool receipt schema state check is invalid")
+
 
 def create_local_session_service(*, project_dir: Optional[str] = None) -> BaseSessionService:
     return LocalSessionService(project_dir=project_dir)