litestar-org · cofin · May 23, 2026 · May 23, 2026 · May 23, 2026 · May 23, 2026
diff --git a/.gitignore b/.gitignore
@@ -77,3 +77,4 @@ tools/scripts/profiles/*.prof
 .beads-credential-key
 .codex
 .mypy_worker*
+.antigravitycli
diff --git a/docs/examples/extensions/adk/backend_config.py b/docs/examples/extensions/adk/backend_config.py
@@ -11,9 +11,12 @@ def test_adk_backend_config() -> None:
     from sqlspec.adapters.adbc import AdbcConfig
 
     adk_config = {
-        "session_table": "adk_sessions",
-        "events_table": "adk_events",
-        "memory_table": "adk_memory_entries",
+        "session_table": "adk_session",
+        "events_table": "adk_event",
+        "app_state_table": "adk_app_state",
+        "user_state_table": "adk_user_state",
+        "metadata_table": "adk_metadata",
+        "memory_table": "adk_memory",
         "memory_use_fts": True,
     }
 

diff --git a/docs/examples/extensions/adk/memory_store.py b/docs/examples/extensions/adk/memory_store.py
@@ -29,7 +29,7 @@ async def _run() -> list[dict[str, object]]:
             "invocation_id": "inv_1",
             "author": "user",
             "timestamp": datetime.now(timezone.utc),
-            "event_json": {
+            "event_data": {
                 "id": "evt_1",
                 "invocation_id": "inv_1",
                 "author": "user",

diff --git a/docs/extensions/adk/api.rst b/docs/extensions/adk/api.rst
@@ -19,12 +19,6 @@ Services
    :show-inheritance:
    :no-index:
 
-.. autoclass:: sqlspec.extensions.adk.memory.SQLSpecSyncMemoryService
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :no-index:
-
 .. autoclass:: SQLSpecArtifactService
    :members:
    :undoc-members:
@@ -40,12 +34,6 @@ Session Stores
    :show-inheritance:
    :no-index:
 
-.. autoclass:: BaseSyncADKStore
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :no-index:
-
 Memory Stores
 =============
 
@@ -55,12 +43,6 @@ Memory Stores
    :show-inheritance:
    :no-index:
 
-.. autoclass:: BaseSyncADKMemoryStore
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :no-index:
-
 Artifact Stores
 ===============
 

diff --git a/docs/extensions/adk/backends.rst b/docs/extensions/adk/backends.rst
@@ -98,6 +98,12 @@ The table below classifies every backend by its ADK support level.
      - Full
      - Full
      - Google Cloud Spanner (cloud-managed).
+   * - bigquery
+     - Analytics-replica
+     - Full (sync-wrapped)
+     - n/a
+     - BigQuery is seconds-latency. Use as the analytics-replica path only; pair
+       with an OLTP-grade ADK adapter for live sessions.
 
 Status Definitions
 ------------------
@@ -120,19 +126,39 @@ Current scoped-state boundary
    buckets across sessions. This is a shared store-contract boundary, not a
    SQLite-specific limitation.
 
+**Analytics-replica**
+   Implemented as a write-mostly mirror for downstream analytics, replay, and
+   audit. Not suitable for synchronous agent inner loops. Use alongside an
+   OLTP-grade ADK adapter (Spanner, PostgreSQL family) for live state.
+
 **Removed**
    Previously available but no longer supported. See the removal notice for
    migration guidance.
 
-Removed Backends
-----------------
+BigQuery (Analytics-Replica)
+----------------------------
+
+The BigQuery ADK store is positioned as the **analytics-replica** path. BigQuery
+query jobs are seconds-latency and BigQuery DML is not transactional across
+separate jobs, so do not use this store for synchronous agent inner loops. Use
+it for analytics, replay, and audit workloads, paired with an OLTP-grade ADK
+adapter (Spanner, PostgreSQL family) for live state.
+
+Schema layout:
+
+- ``adk_session`` — ``PARTITION BY DATE(create_time)``, ``CLUSTER BY app_name, user_id, id``
+- ``adk_event`` — ``PARTITION BY DATE(timestamp)``, ``CLUSTER BY session_id``
+- ``adk_app_state`` — ``CLUSTER BY app_name``
+- ``adk_user_state`` — ``CLUSTER BY app_name, user_id``
+
+Configuration knobs (``extension_config["adk"]["bigquery"]``):
+
+- ``session_lookup_window_days`` — bounds ``list_sessions`` scans (default 30)
+- ``require_partition_filter`` — adds ``OPTIONS(require_partition_filter = TRUE)``
+  on partitioned tables (default ``True``)
 
-**BigQuery** was removed from the ADK backend surface. BigQuery's batch-oriented
-architecture is incompatible with the low-latency, transactional write patterns
-that ADK session and event storage require. If you were using BigQuery for ADK
-storage, migrate to Spanner for a Google-managed operational backend, or to a
-transactional OLTP backend such as PostgreSQL, MySQL, Oracle, SQLite, or
-CockroachDB.
+``ADKConfig.retention.event_ttl_seconds`` is converted to
+``partition_expiration_days`` on the events table when set.
 
 Artifact Storage
 ----------------
@@ -298,9 +324,12 @@ All backends are configured through ``extension_config["adk"]``:
        connection_config={"dsn": "postgresql://localhost/mydb"},
        extension_config={
            "adk": {
-               "session_table": "adk_sessions",
-               "events_table": "adk_events",
-               "memory_table": "adk_memory_entries",
+               "session_table": "adk_session",
+               "events_table": "adk_event",
+               "app_state_table": "adk_app_state",
+               "user_state_table": "adk_user_state",
+               "metadata_table": "adk_metadata",
+               "memory_table": "adk_memory",
                "memory_use_fts": True,
                "owner_id_column": "tenant_id INTEGER NOT NULL",
            }

diff --git a/docs/extensions/adk/index.rst b/docs/extensions/adk/index.rst
@@ -58,6 +58,12 @@ Choose a guide
 
       Table layouts, EventRecord, scoped state, and artifact metadata.
 
+   .. grid-item-card:: Scoped State
+      :link: scoped_state
+      :link-type: doc
+
+      App, user, session, and runtime-only state behavior.
+
    .. grid-item-card:: API Reference
       :link: api
       :link-type: doc
@@ -70,6 +76,12 @@ Choose a guide
 
       Apply schema changes safely over time.
 
+   .. grid-item-card:: Optimizations
+      :link: optimizations
+      :link-type: doc
+
+      Latency-oriented variation catalog and memory embedding presets.
+
 .. toctree::
    :hidden:
 
@@ -78,5 +90,7 @@ Choose a guide
    backends
    adapters
    schema
+   scoped_state
    api
    migrations
+   optimizations
diff --git a/docs/extensions/adk/migrations.rst b/docs/extensions/adk/migrations.rst
@@ -8,7 +8,8 @@ used by your ADK backend, then run them with the SQLSpec migration CLI.
 Schema Bootstrapping
 ====================
 
-You can programmatically create ADK session/event and memory tables with
+You can programmatically create ADK session/event/scoped-state/metadata and
+memory tables with
 ``create_tables()`` / ``ensure_tables()``:
 
 .. code-block:: python
@@ -48,20 +49,43 @@ through your deployment workflow.
    by extension name. Use ``migration_config={"enabled": False}`` to disable
    migrations entirely for a given database config.
 
+Programmatic Cutover with ``recreate_tables()``
+================================================
+
+The base store exposes ``await store.recreate_tables()``, which drops every
+ADK-managed table in FK-safe order and recreates them from the current DDL.
+This is the supported in-place cutover for deployments that own the database
+end-to-end and can tolerate a full ADK schema reset:
+
+.. code-block:: python
+
+   await store.recreate_tables()
+
+``recreate_tables()`` does not touch the SQLSpec migrations runner state, so
+the next ``sqlspec upgrade`` run still sees the unchanged migration history.
+Use ``await store.drop_tables()`` if you need to remove the schema without
+rebuilding it.
+
 Clean-Break Migration Notes
 ============================
 
 If you are upgrading from a pre-clean-break version of the ADK extension,
 note the following schema changes:
 
 - **Events table**: The column layout changed to full-event JSON storage.
-  The ``event_json`` column now stores the entire ADK Event as a JSON blob.
+  The ``event_data`` column now stores the entire ADK Event as a JSON blob.
   Individual event columns (``content``, ``actions``, ``branch``, etc.) have
   been replaced by indexed scalar columns (``invocation_id``, ``author``,
-  ``timestamp``) plus ``event_json``.
-- **Artifact table**: New table (``adk_artifact_versions``) for artifact
+  ``timestamp``) plus ``event_data``.
+- **Scoped state tables**: New ``adk_app_state`` and ``adk_user_state`` tables
+  store ``app:`` and ``user:`` scoped keys. Raw ``adk_session.state`` rows now
+  contain only session-scoped keys; ``SQLSpecSessionService.get_session()``
+  returns the merged ADK view.
+- **Internal metadata table**: New ``adk_metadata`` table seeded with
+  ``schema_version = 1``.
+- **Artifact table**: New table (``adk_artifact``) for artifact
   metadata. Create this table when enabling the artifact service.
-- **BigQuery**: Removed. Migrate to Spanner, PostgreSQL, or any other
-  supported backend.
+- **BigQuery**: Treated as an analytics-replica backend. Use Spanner or a
+  PostgreSQL-family adapter for latency-sensitive live session state.
 
 See :doc:`/usage/migrations` for the full workflow and commands.