functualize-state-sqlite 0.1.0__py3-none-any.whl

functualize_state_sqlite/__init__.py

@@ -0,0 +1,13 @@
+"""Functualize State SQLite Plugin - SQLite-backed state persistence and execution tracking."""
+
+from functualize_state_sqlite._backend import SQLiteStateBackend
+from functualize_state_sqlite._execution_store import SQLiteExecutionStore
+from functualize_state_sqlite._plugin import SQLiteStatePlugin
+from functualize_state_sqlite.plugin import ExecutionStatePlugin
+
+__all__ = [
+    "ExecutionStatePlugin",
+    "SQLiteExecutionStore",
+    "SQLiteStateBackend",
+    "SQLiteStatePlugin",
+]

functualize_state_sqlite/_backend.py

@@ -0,0 +1,160 @@
+"""SQLite StateBackend implementation.
+
+Implements the StateBackend protocol from functualize-state using SQLite
+in WAL mode for concurrent access. Values are JSON-encoded for storage.
+Uses only stdlib sqlite3 (zero external dependencies).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+__all__ = ["SQLiteStateBackend"]
+
+logger = logging.getLogger(__name__)
+
+_STATE_SCHEMA_SQL = """\
+CREATE TABLE IF NOT EXISTS kv_state (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    updated_at REAL NOT NULL
+);
+"""
+
+
+class SQLiteStateBackend:
+    """StateBackend protocol implementation backed by SQLite.
+
+    Provides persistent key-value state storage with JSON-encoded values.
+    Uses WAL mode for concurrent read access without blocking writes.
+
+    Args:
+        db_path: Path to the SQLite database file. If None, defaults to
+            `.functualize/state.db` relative to the current working directory.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        if db_path is None:
+            self._db_path = Path.cwd() / ".functualize" / "state.db"
+        else:
+            self._db_path = Path(db_path)
+
+        self._conn: sqlite3.Connection | None = None
+        self._initialized = False
+
+    @property
+    def db_path(self) -> Path:
+        """The resolved path to the database file."""
+        return self._db_path
+
+    def _ensure_initialized(self) -> sqlite3.Connection:
+        """Ensure the database is initialized and return the connection."""
+        if self._conn is not None and self._initialized:
+            return self._conn
+
+        # Ensure the directory exists
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open connection
+        self._conn = sqlite3.connect(
+            str(self._db_path),
+            timeout=10.0,
+            check_same_thread=False,
+        )
+
+        # Enable WAL mode for concurrent access
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA synchronous = NORMAL")
+        self._conn.commit()
+
+        # Create schema
+        self._conn.executescript(_STATE_SCHEMA_SQL)
+        self._conn.commit()
+
+        self._initialized = True
+        logger.debug("SQLiteStateBackend initialized at %s", self._db_path)
+        return self._conn
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value by key, returning default if not found.
+
+        The stored JSON value is deserialized back to a Python object.
+        """
+        conn = self._ensure_initialized()
+        cursor = conn.execute(
+            "SELECT value FROM kv_state WHERE key = ?",
+            (key,),
+        )
+        row = cursor.fetchone()
+        if row is None:
+            return default
+        return json.loads(row[0])
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value for a key.
+
+        The value is JSON-encoded before storage.
+        """
+        conn = self._ensure_initialized()
+        value_json = json.dumps(value)
+        now = time.time()
+        conn.execute(
+            "INSERT OR REPLACE INTO kv_state (key, value, updated_at) VALUES (?, ?, ?)",
+            (key, value_json, now),
+        )
+        conn.commit()
+
+    def delete(self, key: str) -> None:
+        """Delete a key from the state backend.
+
+        No-op if the key does not exist.
+        """
+        conn = self._ensure_initialized()
+        conn.execute("DELETE FROM kv_state WHERE key = ?", (key,))
+        conn.commit()
+
+    def keys(self, prefix: str = "") -> list[str]:
+        """Return all keys, optionally filtered by prefix."""
+        conn = self._ensure_initialized()
+        if prefix:
+            cursor = conn.execute(
+                "SELECT key FROM kv_state WHERE key LIKE ? ESCAPE '\\'",
+                (self._escape_like(prefix) + "%",),
+            )
+        else:
+            cursor = conn.execute("SELECT key FROM kv_state")
+        return [row[0] for row in cursor.fetchall()]
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except sqlite3.Error as e:
+                logger.warning("Error closing SQLiteStateBackend connection: %s", e)
+            finally:
+                self._conn = None
+                self._initialized = False
+
+    @staticmethod
+    def _escape_like(value: str) -> str:
+        """Escape special characters in a LIKE pattern."""
+        return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+
+    def __enter__(self) -> SQLiteStateBackend:
+        """Context manager entry — initialize if needed."""
+        self._ensure_initialized()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Context manager exit — close connection."""
+        self.close()
+
+    def __del__(self) -> None:
+        """Ensure connection is closed on garbage collection."""
+        self.close()

functualize_state_sqlite/_execution_store.py

@@ -0,0 +1,379 @@
+"""SQLite implementation of the ExecutionStore protocol.
+
+Provides persistent execution record and phase tracking backed by SQLite,
+conforming to the ExecutionStore protocol defined in functualize-state SDK.
+
+Shares the database file with the SQLiteStateBackend to keep all persistent
+state in a single database. Uses only stdlib sqlite3 (zero external deps).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from functualize_state._types import ExecutionRecord, PhaseRecord
+
+__all__ = ["SQLiteExecutionStore"]
+
+logger = logging.getLogger(__name__)
+
+# SQL to create the ExecutionStore-specific tables following the design schema.
+_EXECUTION_STORE_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id TEXT PRIMARY KEY,
+    started_at REAL NOT NULL,
+    metadata TEXT
+);
+
+CREATE TABLE IF NOT EXISTS executions (
+    execution_id TEXT PRIMARY KEY,
+    job_name TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'running',
+    started_at REAL NOT NULL,
+    ended_at REAL,
+    duration_ms REAL,
+    kwargs TEXT,
+    result TEXT,
+    FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+CREATE TABLE IF NOT EXISTS phases (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    execution_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    status TEXT NOT NULL,
+    started_at REAL NOT NULL,
+    ended_at REAL,
+    duration_ms REAL,
+    FOREIGN KEY (execution_id) REFERENCES executions(execution_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_executions_session_id
+    ON executions(session_id);
+
+CREATE INDEX IF NOT EXISTS idx_phases_execution_id
+    ON phases(execution_id);
+"""
+
+
+class SQLiteExecutionStore:
+    """SQLite-backed implementation of the ExecutionStore protocol.
+
+    Stores execution records, phases, and sessions using the SQL schema
+    defined in the design document. Uses JSON encoding for complex types
+    (kwargs dict, result value).
+
+    Shares the same database file as the SQLiteStateBackend to keep all
+    persistent state collocated. Connection management is handled internally
+    using the same WAL mode configuration.
+
+    Args:
+        db_path: Path to the SQLite database file. If None, defaults to
+            `.functualize/state.db` relative to the current working directory.
+            Should match the path used by SQLiteStateBackend.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        if db_path is None:
+            self._db_path = Path.cwd() / ".functualize" / "state.db"
+        else:
+            self._db_path = Path(db_path)
+
+        self._conn: sqlite3.Connection | None = None
+        self._initialized = False
+
+    @property
+    def db_path(self) -> Path:
+        """The resolved path to the database file."""
+        return self._db_path
+
+    def _ensure_initialized(self) -> sqlite3.Connection:
+        """Ensure the database is initialized and return the connection.
+
+        Creates the database directory, opens a connection with WAL mode,
+        and initializes the execution store schema tables.
+        """
+        if self._conn is not None and self._initialized:
+            return self._conn
+
+        # Ensure the directory exists
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Open connection with same settings as SQLiteStateBackend
+        self._conn = sqlite3.connect(
+            str(self._db_path),
+            timeout=10.0,
+            check_same_thread=False,
+        )
+
+        # Enable WAL mode for concurrent access
+        self._conn.execute("PRAGMA journal_mode = WAL")
+        self._conn.execute("PRAGMA synchronous = NORMAL")
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.commit()
+
+        # Create execution store schema
+        self._conn.executescript(_EXECUTION_STORE_SCHEMA)
+        self._conn.commit()
+
+        self._initialized = True
+        logger.debug("SQLiteExecutionStore initialized at %s", self._db_path)
+        return self._conn
+
+    # ─── ExecutionStore Protocol Methods ──────────────────────────────
+
+    def insert_execution(self, record: ExecutionRecord) -> str:
+        """Insert an execution record, returning the execution ID.
+
+        Ensures the session exists before inserting the execution. If the
+        session doesn't exist yet, it is created automatically.
+
+        Args:
+            record: The ExecutionRecord to persist.
+
+        Returns:
+            The execution_id from the record.
+        """
+        conn = self._ensure_initialized()
+
+        # Ensure the session exists (upsert — don't overwrite existing)
+        conn.execute(
+            "INSERT OR IGNORE INTO sessions (session_id, started_at) VALUES (?, ?)",
+            (record.session_id, record.started_at),
+        )
+
+        # Serialize complex fields
+        kwargs_json = json.dumps(record.kwargs) if record.kwargs else None
+        result_json = (
+            _safe_json_encode(record.result) if record.result is not None else None
+        )
+
+        conn.execute(
+            """INSERT INTO executions
+               (execution_id, job_name, session_id, status, started_at,
+                ended_at, duration_ms, kwargs, result)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                record.execution_id,
+                record.job_name,
+                record.session_id,
+                record.status,
+                record.started_at,
+                record.ended_at,
+                record.duration_ms,
+                kwargs_json,
+                result_json,
+            ),
+        )
+        conn.commit()
+        return record.execution_id
+
+    def update_execution(self, execution_id: str, **updates: Any) -> None:
+        """Update fields on an existing execution record.
+
+        Supports updating: status, ended_at, duration_ms, kwargs, result.
+
+        Args:
+            execution_id: The execution to update.
+            **updates: Field names and their new values.
+        """
+        if not updates:
+            return
+
+        conn = self._ensure_initialized()
+        set_clauses: list[str] = []
+        params: list[Any] = []
+
+        for field_name, value in updates.items():
+            if field_name == "kwargs":
+                set_clauses.append("kwargs = ?")
+                params.append(json.dumps(value) if value is not None else None)
+            elif field_name == "result":
+                set_clauses.append("result = ?")
+                params.append(_safe_json_encode(value) if value is not None else None)
+            elif field_name in ("status", "ended_at", "duration_ms"):
+                set_clauses.append(f"{field_name} = ?")
+                params.append(value)
+            else:
+                logger.warning(
+                    "Ignoring unknown update field '%s' for execution %s",
+                    field_name,
+                    execution_id,
+                )
+
+        if not set_clauses:
+            return
+
+        params.append(execution_id)
+        sql = f"UPDATE executions SET {', '.join(set_clauses)} WHERE execution_id = ?"
+
+        conn.execute(sql, tuple(params))
+        conn.commit()
+
+    def get_session_executions(
+        self, session_id: str, limit: int = 50
+    ) -> list[ExecutionRecord]:
+        """Get execution records for a session, ordered by start time descending.
+
+        Args:
+            session_id: The session to query.
+            limit: Maximum number of results (default 50).
+
+        Returns:
+            List of ExecutionRecord instances.
+        """
+        conn = self._ensure_initialized()
+
+        cursor = conn.execute(
+            """SELECT execution_id, job_name, session_id, status,
+                      started_at, ended_at, duration_ms, kwargs, result
+               FROM executions
+               WHERE session_id = ?
+               ORDER BY started_at DESC
+               LIMIT ?""",
+            (session_id, limit),
+        )
+        rows = cursor.fetchall()
+        return [_row_to_execution_record(row) for row in rows]
+
+    def insert_phase(self, execution_id: str, phase: PhaseRecord) -> None:
+        """Insert a phase record for an execution.
+
+        Args:
+            execution_id: The execution this phase belongs to.
+            phase: The PhaseRecord to persist.
+        """
+        conn = self._ensure_initialized()
+
+        conn.execute(
+            """INSERT INTO phases
+               (execution_id, name, status, started_at, ended_at, duration_ms)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (
+                execution_id,
+                phase.name,
+                phase.status,
+                phase.started_at,
+                phase.ended_at,
+                phase.duration_ms,
+            ),
+        )
+        conn.commit()
+
+    def get_execution_phases(self, execution_id: str) -> list[PhaseRecord]:
+        """Get all phase records for an execution, ordered by start time.
+
+        Args:
+            execution_id: The execution to query phases for.
+
+        Returns:
+            List of PhaseRecord instances ordered by started_at ascending.
+        """
+        conn = self._ensure_initialized()
+
+        cursor = conn.execute(
+            """SELECT name, status, started_at, ended_at, duration_ms
+               FROM phases
+               WHERE execution_id = ?
+               ORDER BY started_at ASC""",
+            (execution_id,),
+        )
+        rows = cursor.fetchall()
+        return [
+            PhaseRecord(
+                name=row[0],
+                status=row[1],
+                started_at=row[2],
+                ended_at=row[3],
+                duration_ms=row[4],
+            )
+            for row in rows
+        ]
+
+    # ─── Lifecycle ────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._conn is not None:
+            try:
+                self._conn.close()
+            except sqlite3.Error as e:
+                logger.warning("Error closing SQLiteExecutionStore connection: %s", e)
+            finally:
+                self._conn = None
+                self._initialized = False
+
+    def __enter__(self) -> SQLiteExecutionStore:
+        """Context manager entry — initialize if needed."""
+        self._ensure_initialized()
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        """Context manager exit — close connection."""
+        self.close()
+
+    def __del__(self) -> None:
+        """Ensure connection is closed on garbage collection."""
+        self.close()
+
+
+# ─── Module-Level Helpers ─────────────────────────────────────────────
+
+
+def _safe_json_encode(value: Any) -> str | None:
+    """Encode a value to JSON, handling non-serializable values gracefully.
+
+    Args:
+        value: Any Python value to encode.
+
+    Returns:
+        JSON string, or None if value is None.
+    """
+    if value is None:
+        return None
+    try:
+        return json.dumps(value)
+    except (TypeError, ValueError, OverflowError):
+        type_name = type(value).__name__
+        return json.dumps(f"<non-serializable: {type_name}>")
+
+
+def _row_to_execution_record(row: tuple[Any, ...]) -> ExecutionRecord:
+    """Convert a database row tuple to an ExecutionRecord instance.
+
+    Expected column order: execution_id, job_name, session_id, status,
+    started_at, ended_at, duration_ms, kwargs, result.
+    """
+    kwargs_raw = row[7]
+    result_raw = row[8]
+
+    kwargs: dict[str, Any] = {}
+    if kwargs_raw is not None:
+        try:
+            kwargs = json.loads(kwargs_raw)
+        except (json.JSONDecodeError, TypeError):
+            kwargs = {}
+
+    result: Any = None
+    if result_raw is not None:
+        try:
+            result = json.loads(result_raw)
+        except (json.JSONDecodeError, TypeError):
+            result = result_raw
+
+    return ExecutionRecord(
+        execution_id=row[0],
+        job_name=row[1],
+        session_id=row[2],
+        status=row[3],
+        started_at=row[4],
+        ended_at=row[5],
+        duration_ms=row[6],
+        kwargs=kwargs,
+        result=result,
+    )

functualize_state_sqlite/_migrations.py

@@ -0,0 +1,157 @@
+"""Schema migration system for the SQLite state plugin.
+
+Provides version tracking and sequential migration upgrades using a
+`schema_version` table. Each migration is a function that takes a
+sqlite3.Connection and applies schema changes for that version.
+
+Uses only stdlib sqlite3 (zero external dependencies).
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+from collections.abc import Callable
+
+__all__ = ["migrate", "get_current_version", "LATEST_VERSION"]
+
+logger = logging.getLogger(__name__)
+
+# Type alias for migration functions
+MigrationFn = Callable[[sqlite3.Connection], None]
+
+
+def _migration_v1(conn: sqlite3.Connection) -> None:
+    """Initial migration: create state, executions, phases, and sessions tables."""
+    conn.executescript("""\
+        CREATE TABLE IF NOT EXISTS state (
+            key TEXT PRIMARY KEY,
+            value TEXT NOT NULL,
+            updated_at REAL NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS sessions (
+            session_id TEXT PRIMARY KEY,
+            started_at REAL NOT NULL,
+            metadata TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS executions (
+            execution_id TEXT PRIMARY KEY,
+            job_name TEXT NOT NULL,
+            session_id TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'running',
+            started_at REAL NOT NULL,
+            ended_at REAL,
+            duration_ms REAL,
+            kwargs TEXT,
+            result TEXT,
+            FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+        );
+
+        CREATE TABLE IF NOT EXISTS phases (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            execution_id TEXT NOT NULL,
+            name TEXT NOT NULL,
+            status TEXT NOT NULL,
+            started_at REAL NOT NULL,
+            ended_at REAL,
+            duration_ms REAL,
+            FOREIGN KEY (execution_id) REFERENCES executions(execution_id)
+        );
+    """)
+
+
+# Registry of all migrations, keyed by version number.
+# Migrations are applied sequentially from current version + 1 to LATEST_VERSION.
+_MIGRATIONS: dict[int, MigrationFn] = {
+    1: _migration_v1,
+}
+
+# The latest schema version supported by this plugin.
+LATEST_VERSION: int = max(_MIGRATIONS.keys())
+
+
+def _ensure_schema_version_table(conn: sqlite3.Connection) -> None:
+    """Create the schema_version table if it doesn't exist."""
+    conn.execute("""\
+        CREATE TABLE IF NOT EXISTS schema_version (
+            version INTEGER PRIMARY KEY,
+            applied_at REAL NOT NULL
+        )
+    """)
+    conn.commit()
+
+
+def get_current_version(conn: sqlite3.Connection) -> int:
+    """Get the current schema version from the database.
+
+    Returns 0 if no migrations have been applied yet.
+
+    Args:
+        conn: An open sqlite3 connection.
+
+    Returns:
+        The highest version number that has been applied, or 0 if none.
+    """
+    _ensure_schema_version_table(conn)
+    cursor = conn.execute("SELECT MAX(version) FROM schema_version")
+    row = cursor.fetchone()
+    if row is None or row[0] is None:
+        return 0
+    return int(row[0])
+
+
+def migrate(conn: sqlite3.Connection) -> int:
+    """Apply all pending migrations to bring the database up to LATEST_VERSION.
+
+    Creates the schema_version table if it doesn't exist, checks the current
+    version, and applies migrations sequentially from current + 1 to
+    LATEST_VERSION.
+
+    Each migration is executed within a transaction. If a migration fails,
+    the transaction is rolled back and the error is raised.
+
+    Args:
+        conn: An open sqlite3 connection.
+
+    Returns:
+        The version the database is now at after migrations.
+
+    Raises:
+        sqlite3.Error: If a migration fails to apply.
+    """
+    _ensure_schema_version_table(conn)
+    current = get_current_version(conn)
+
+    if current >= LATEST_VERSION:
+        logger.debug("Schema is up to date (version %d)", current)
+        return current
+
+    logger.info(
+        "Migrating schema from version %d to %d",
+        current,
+        LATEST_VERSION,
+    )
+
+    for version in range(current + 1, LATEST_VERSION + 1):
+        migration_fn = _MIGRATIONS.get(version)
+        if migration_fn is None:
+            raise RuntimeError(f"Missing migration function for version {version}")
+
+        logger.debug("Applying migration version %d", version)
+        try:
+            migration_fn(conn)
+            conn.execute(
+                "INSERT INTO schema_version (version, applied_at) VALUES (?, ?)",
+                (version, time.time()),
+            )
+            conn.commit()
+            logger.info("Applied migration version %d", version)
+        except sqlite3.Error:
+            conn.rollback()
+            logger.error("Failed to apply migration version %d", version)
+            raise
+
+    return LATEST_VERSION