Skip to main content
Meerkat owns the canonical session and runtime lifecycle: input acceptance, turn execution, deduplication, retire/reset semantics, and durable recovery. MobKit adds session-store adapters that support MobKit’s operational workflows, console views, and integration surfaces.
This page describes MobKit-specific storage adapters. It does not replace Meerkat’s own runtime-backed session durability model.

​
MobKit storage backends

​
JSON file store

The default adapter writes session state snapshots as JSON files to a local directory. Each session gets its own file, and concurrent access is managed through lock files.
Lock-based concurrency. Before writing, the store acquires a lock file ({session_id}.lock). The lock contains a JsonStoreLockRecord with the process ID and acquisition timestamp. Stale lock recovery. If a process crashes while holding a lock, the lock becomes stale. On the next access attempt, the store checks whether the PID in the lock record is still alive. Dead PIDs trigger automatic lock recovery — the stale lock is removed and a new one is acquired.

​
BigQuery adapter

For production-oriented deployments, the BigQuery adapter writes session rows to a configured dataset and table:
BigQuery naming is validated:
  • Dataset and table names must be non-empty
  • Only alphanumeric characters, underscores, and hyphens are allowed
BigQuery naming validation rejects special characters to prevent injection. Names like my.dataset or table;DROP are rejected.

​
Session persistence rows

Session state is serialized as SessionPersistenceRow records:

​
Session store contracts

The SessionStoreContract defines the operations every backend must implement: Contracts are verified by integration tests that run the same test suite against every backend implementation.

​
Materialization

MobKit provides two materialization functions for session inspection:
  • materialize_latest_session_rows — returns the most recent row per session
  • materialize_live_session_rows — returns rows for currently active sessions
These power MobKit’s operational session inspection features and adapter-specific APIs.

​
Runtime correlation

When MobKit accepts a mobkit/send_message request, the response includes the Meerkat session_id that accepted the message. Treat that value as the canonical correlation handle for follow-up inspection, debugging, and resume-aware flows.

​
See also