diffbutler 0.5.0__py3-none-any.whl

diffbutler/store/dashboard.py

@@ -0,0 +1,201 @@
+"""Atomic local actions and offline history projections."""
+
+from datetime import UTC
+from uuid import UUID
+
+from sqlalchemy import select, text
+
+from diffbutler.domain.dashboard import CycleRecord
+from diffbutler.domain.forge import Account
+from diffbutler.domain.review import ReviewConflict
+from diffbutler.store.database import Database
+from diffbutler.store.models import (
+    AIRun,
+    CleanupJob,
+    ForgeAccount,
+    ObservedActivity,
+    PRMonitor,
+    ReviewSession,
+    ReviewTask,
+    UIPreference,
+    utc_now,
+)
+from diffbutler.store.queue import EVENT_ADAPTER, PR_ADAPTER
+from diffbutler.store.review import record, session_record, transition
+
+
+class SQLiteDashboardStore:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    async def reset_task(self, task_id: UUID) -> None:
+        """Forget active monitoring and invalidate work, retaining history and cleanup ownership."""
+        async with self.database.sessions() as db:
+            await db.execute(text("BEGIN IMMEDIATE"))
+            task = await db.get(ReviewTask, task_id)
+            if task is None or task.completed_at is not None:
+                raise ReviewConflict("Review task is missing or completed")
+            monitor = await db.get(PRMonitor, (task.account_id, task.pull_request_id))
+            if monitor is None or monitor.task_id != task.id:
+                raise ReviewConflict("Review task is no longer current")
+            # Older migrated cycles may still rely on the monitor for their snapshot.
+            cycles = await db.scalars(
+                select(ReviewTask).where(
+                    ReviewTask.account_id == task.account_id,
+                    ReviewTask.pull_request_id == task.pull_request_id,
+                )
+            )
+            for cycle in cycles:
+                if not cycle.snapshot_json:
+                    cycle.snapshot_json = monitor.snapshot_json
+            await transition(db, task, "DONE")
+            task.completed_at = utc_now()
+            task.completion_reason = "local_reset"
+            task.completion_source = "local"
+            task.completed_head_sha = str(monitor.snapshot_json["head_sha"])
+            task.following = False
+            task.request_sources_json = []
+            runs = await db.scalars(
+                select(AIRun).where(
+                    AIRun.review_task_id == task_id, AIRun.status.in_(("queued", "running"))
+                )
+            )
+            for run in runs:
+                run.status = "cancelled"
+                run.status_reason = "PR reset locally"
+                run.finished_at = utc_now()
+            # Claims remain held until their supervisors establish process exit.
+            db.add(CleanupJob(review_task_id=task_id))
+            await db.delete(monitor)
+            await db.commit()
+
+    async def choose_state(self, task_id: UUID, *, waiting: bool) -> None:
+        async with self.database.sessions() as db:
+            await db.execute(text("BEGIN IMMEDIATE"))
+            task = await db.get(ReviewTask, task_id)
+            if task is None or task.completed_at is not None:
+                raise ReviewConflict("Review task is missing or completed")
+            monitor = await db.get(PRMonitor, (task.account_id, task.pull_request_id))
+            if (
+                monitor is None
+                or monitor.task_id != task.id
+                or monitor.snapshot_json["state"] != "open"
+            ):
+                raise ReviewConflict("Review task is no longer current and open")
+            now = utc_now()
+            await transition(
+                db, task, "PENDING_AUTHOR_CHANGES" if waiting else "PENDING_HUMAN_REVIEW"
+            )
+            # Events predating this explicit choice cannot override it on a retry.
+            task.state_event_watermark = max(
+                task.state_event_watermark or "",
+                monitor.review_key,
+                now.isoformat(timespec="microseconds") + ":~",
+            )
+            if not waiting:
+                task.opened_at = now
+            monitor.notice = (
+                "Waiting for author chosen locally" if waiting else "Manual review chosen locally"
+            )
+            runs = await db.scalars(
+                select(AIRun).where(
+                    AIRun.review_task_id == task_id, AIRun.status.in_(("queued", "running"))
+                )
+            )
+            for run in runs:
+                run.status = "cancelled"
+                run.finished_at = now
+            await db.commit()
+
+    async def refresh_pending(self, task_id: UUID) -> None:
+        async with self.database.sessions() as db:
+            await db.execute(text("BEGIN IMMEDIATE"))
+            task = await db.get(ReviewTask, task_id)
+            if task is None:
+                raise ReviewConflict("Task does not exist")
+            monitor = await db.get(PRMonitor, (task.account_id, task.pull_request_id))
+            identity = await db.get(ForgeAccount, task.account_id)
+            if monitor and identity:
+                monitor.refresh_pending = True
+                identity.version += 1
+            await db.commit()
+
+    async def preferences(self) -> dict[str, str]:
+        async with self.database.sessions() as db:
+            return {row.key: row.value for row in await db.scalars(select(UIPreference))}
+
+    async def set_preference(self, key: str, value: str) -> None:
+        async with self.database.sessions() as db:
+            await db.execute(text("BEGIN IMMEDIATE"))
+            row = await db.get(UIPreference, key)
+            if row is None:
+                db.add(UIPreference(key=key, value=value))
+            else:
+                row.value = value
+            await db.commit()
+
+    async def cycles(self) -> tuple[CycleRecord, ...]:
+        async with self.database.sessions() as db:
+            await db.execute(text("BEGIN"))
+            rows = await db.execute(
+                select(ReviewTask, ForgeAccount, PRMonitor)
+                .join(ForgeAccount, ReviewTask.account_id == ForgeAccount.account_id)
+                .outerjoin(
+                    PRMonitor,
+                    (PRMonitor.account_id == ReviewTask.account_id)
+                    & (PRMonitor.pull_request_id == ReviewTask.pull_request_id),
+                )
+                .order_by(
+                    ReviewTask.first_seen_at.desc(), ReviewTask.cycle_number.desc(), ReviewTask.id
+                )
+            )
+            result: list[CycleRecord] = []
+            for task, identity, monitor in rows:
+                runs = tuple(
+                    record(run)
+                    for run in await db.scalars(
+                        select(AIRun)
+                        .where(AIRun.review_task_id == task.id)
+                        .order_by(AIRun.requested_at, AIRun.attempt)
+                    )
+                )
+                sessions = tuple(
+                    session_record(row)
+                    for row in await db.scalars(
+                        select(ReviewSession)
+                        .where(ReviewSession.review_task_id == task.id)
+                        .order_by(ReviewSession.created_at)
+                    )
+                )
+                receipts = tuple(
+                    EVENT_ADAPTER.validate_json(row.payload_json)
+                    for row in await db.scalars(
+                        select(ObservedActivity)
+                        .where(ObservedActivity.review_task_id == task.id)
+                        .order_by(ObservedActivity.event_id)
+                    )
+                )
+                cleanup = await db.scalar(
+                    select(CleanupJob).where(CleanupJob.review_task_id == task.id)
+                )
+                result.append(
+                    CycleRecord(
+                        task.id,
+                        Account(identity.forge, identity.login, identity.login),
+                        PR_ADAPTER.validate_python(
+                            task.snapshot_json or (monitor.snapshot_json if monitor else {})
+                        ),
+                        task.cycle_number,
+                        task.state,
+                        task.completed_at.replace(tzinfo=UTC) if task.completed_at else None,
+                        task.completion_reason,
+                        task.completed_head_sha,
+                        cleanup.status if cleanup else "not_requested",
+                        cleanup.last_error if cleanup else None,
+                        task.opened_at.replace(tzinfo=UTC) if task.opened_at else None,
+                        runs,
+                        sessions,
+                        receipts,
+                    )
+                )
+            return tuple(result)

diffbutler/store/database.py

@@ -0,0 +1,172 @@
+"""Async SQLite startup and packaged migrations, with consistent pre-upgrade backups."""
+
+import asyncio
+import sqlite3
+from contextlib import closing
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from uuid import uuid4
+
+import aiosqlite
+from alembic import command
+from alembic.config import Config
+from alembic.migration import MigrationContext
+from alembic.script import ScriptDirectory
+from sqlalchemy import Connection, event, inspect
+from sqlalchemy.engine import URL, AdaptedConnection, make_url
+from sqlalchemy.exc import ArgumentError
+from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
+
+
+class DatabaseError(ValueError):
+    """A safe diagnostic that does not expose connection credentials."""
+
+
+@dataclass(frozen=True)
+class DatabaseStatus:
+    revision: str
+    migrated: bool
+    backup: Path | None
+
+
+def migration_config(connection: Connection | None = None) -> Config:
+    config = Config()
+    config.set_main_option("script_location", str(Path(__file__).parent / "migrations"))
+    if connection is not None:
+        config.attributes["connection"] = connection
+    return config
+
+
+def sqlite_url(value: str) -> URL:
+    try:
+        url = make_url(value)
+    except ArgumentError, ValueError:
+        raise DatabaseError("db.url: invalid SQLAlchemy URL") from None
+    if url.drivername != "sqlite+aiosqlite":
+        raise DatabaseError(
+            "db.url: Only sqlite+aiosqlite is supported; PostgreSQL/MySQL are not implemented"
+        )
+    if url.username or url.password or url.host or url.port or url.query:
+        raise DatabaseError(
+            "db.url: SQLite requires a local file path without credentials or query options"
+        )
+    if not url.database or url.database == ":memory:":
+        raise DatabaseError("db.url: use a persistent SQLite file")
+    return url.set(database=str(Path(url.database).expanduser().absolute()))
+
+
+async def configure_sqlite(connection: aiosqlite.Connection) -> None:
+    """Enable WAL without blocking the event loop during startup contention."""
+    try:
+        async with connection.cursor() as cursor:
+            await cursor.execute("PRAGMA busy_timeout=5000")
+            await cursor.execute("PRAGMA foreign_keys=ON")
+            deadline = asyncio.get_running_loop().time() + 5
+            while True:
+                try:
+                    await cursor.execute("PRAGMA journal_mode=WAL")
+                    break
+                except sqlite3.OperationalError as exc:
+                    # SQLite may return BUSY immediately on a journal-mode lock
+                    # upgrade, even with busy_timeout set. Retry after yielding.
+                    if (
+                        getattr(exc, "sqlite_errorcode", None) != sqlite3.SQLITE_BUSY
+                        or asyncio.get_running_loop().time() >= deadline
+                    ):
+                        raise
+                    await asyncio.sleep(0.05)
+    except BaseException:
+        # Connect-event failures can occur before SQLAlchemy owns a pool record.
+        await connection.close()
+        raise
+
+
+def _configure_sqlite(connection: AdaptedConnection, _record: object) -> None:
+    connection.run_async(configure_sqlite)
+
+
+def backup_sqlite(path: Path) -> Path:
+    """Save a consistent snapshot beside the database before changing its schema."""
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    destination = path.with_name(f"{path.name}.{stamp}.{uuid4().hex}.bak")
+    # SQLite's backup API includes committed WAL contents, unlike copying the file.
+    try:
+        with (
+            closing(sqlite3.connect(path)) as source,
+            closing(sqlite3.connect(destination)) as target,
+        ):
+            source.backup(target)
+    except sqlite3.Error:
+        destination.unlink(missing_ok=True)
+        raise DatabaseError(
+            "database backup failed; check file permissions and SQLite integrity"
+        ) from None
+    except BaseException:
+        destination.unlink(missing_ok=True)
+        raise
+    return destination
+
+
+class Database:
+    """Owns the engine/session factory; callers must close it after use."""
+
+    def __init__(self, url: str) -> None:
+        self.url = sqlite_url(url)
+        assert self.url.database is not None
+        self.path = Path(self.url.database)
+        self.engine: AsyncEngine = create_async_engine(self.url)
+        event.listen(self.engine.sync_engine, "connect", _configure_sqlite)
+        self.sessions = async_sessionmaker(self.engine, expire_on_commit=False)
+
+    async def initialize(self, *, auto_migrate: bool = True) -> DatabaseStatus:
+        existed = self.path.exists()
+        if not auto_migrate and not existed:
+            raise DatabaseError("database is missing; enable db.auto_migrate to initialize it")
+        if auto_migrate:
+            await asyncio.to_thread(self.path.parent.mkdir, parents=True, exist_ok=True)
+        async with self.engine.connect() as connection:
+            # Serialize startup migrations across processes. No tables are changed
+            # until a consistent backup has completed successfully.
+            await connection.exec_driver_sql("BEGIN IMMEDIATE")
+            current = await connection.run_sync(
+                lambda conn: MigrationContext.configure(conn).get_current_heads()
+            )
+            scripts = ScriptDirectory.from_config(migration_config())
+            head = scripts.get_current_head()
+            assert head is not None
+            if current == (head,):
+                await connection.commit()
+                return DatabaseStatus(head, False, None)
+            known = {revision.revision for revision in scripts.walk_revisions()}
+            if current and (len(current) != 1 or current[0] not in known):
+                raise DatabaseError(
+                    "database revision is unknown to this version; "
+                    "use the matching DiffButler release"
+                )
+            tables = await connection.run_sync(lambda conn: inspect(conn).get_table_names())
+            if not current and set(tables) - {"alembic_version"}:
+                raise DatabaseError(
+                    "database has unversioned tables; refusing to adopt or overwrite it"
+                )
+            if not auto_migrate:
+                raise DatabaseError("database migrations are not current; enable db.auto_migrate")
+            backup = await asyncio.to_thread(backup_sqlite, self.path) if existed else None
+            await connection.run_sync(lambda conn: command.upgrade(migration_config(conn), "head"))
+            await connection.commit()
+            return DatabaseStatus(head, True, backup)
+
+    async def close(self) -> None:
+        # Cancellation during disposal can interrupt aiosqlite.close after the
+        # pool has discarded the connection. Finish closing it before propagating
+        # cancellation, including repeated cancellation during app shutdown.
+        closing = asyncio.create_task(self.engine.dispose())
+        cancelled = False
+        while not closing.done():
+            try:
+                await asyncio.shield(closing)
+            except asyncio.CancelledError:
+                cancelled = True
+        closing.result()
+        if cancelled:
+            raise asyncio.CancelledError

diffbutler/store/lifecycle.py

@@ -0,0 +1,247 @@
+"""Short transactions for foreground leases and completion-triggered cleanup."""
+
+from datetime import timedelta
+from uuid import UUID
+
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from diffbutler.domain.lifecycle import (
+    CleanupClaim,
+    CleanupSession,
+    CleanupStatus,
+    ForegroundLease,
+    HeldOperation,
+)
+from diffbutler.domain.review import ReviewConflict
+from diffbutler.store.database import Database
+from diffbutler.store.models import (
+    AIRun,
+    CleanupJob,
+    PRMonitor,
+    ReviewSession,
+    ReviewTask,
+    RunClaim,
+    utc_now,
+)
+from diffbutler.store.models import CleanupClaim as ClaimModel
+from diffbutler.store.models import ForegroundLease as LeaseModel
+
+
+async def _background_owned(db: AsyncSession, task_id: UUID) -> bool:
+    active = await db.scalar(
+        select(AIRun.id).where(
+            AIRun.review_task_id == task_id, AIRun.status.in_(("queued", "running"))
+        )
+    )
+    held = await db.scalar(
+        select(RunClaim.token).join(AIRun).where(AIRun.review_task_id == task_id)
+    )
+    return active is not None or held is not None
+
+
+class SQLiteLifecycleStore:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    async def _begin(self, db: AsyncSession) -> None:
+        connection = await db.connection()
+        await connection.exec_driver_sql("BEGIN IMMEDIATE")
+
+    async def cleanup_status(self) -> CleanupStatus:
+        async with self.database.sessions() as db:
+            rows = await db.execute(
+                select(CleanupJob.status, func.count()).group_by(CleanupJob.status)
+            )
+            counts = dict(rows.all())
+            return CleanupStatus(
+                succeeded=counts.get("succeeded", 0),
+                pending=counts.get("pending", 0),
+                running=counts.get("running", 0),
+                failed=counts.get("failed", 0),
+            )
+
+    async def held_operations(self) -> tuple[HeldOperation, ...]:
+        """Expose durable ownership for recovery; ages are not evidence of exit."""
+        async with self.database.sessions() as db:
+            foreground = await db.scalars(select(LeaseModel).order_by(LeaseModel.acquired_at))
+            result = [
+                HeldOperation(row.token, "foreground", row.session_id, row.acquired_at)
+                for row in foreground
+            ]
+            cleanup = await db.scalars(select(ClaimModel).order_by(ClaimModel.acquired_at))
+            result.extend(
+                HeldOperation(row.token, "cleanup", row.job_id, row.acquired_at) for row in cleanup
+            )
+            background = await db.execute(select(RunClaim, AIRun).join(AIRun))
+            result.extend(
+                HeldOperation(claim.token, "background", run.id, run.started_at or run.requested_at)
+                for claim, run in background
+            )
+            return tuple(result)
+
+    async def acquire_foreground(self, session_id: UUID) -> ForegroundLease:
+        async with self.database.sessions() as db:
+            await self._begin(db)
+            session = await db.get(ReviewSession, session_id)
+            if (
+                session is None
+                or session.status == "cleaned"
+                or session.cleanup_status != "not_requested"
+            ):
+                raise ReviewConflict("Session is missing, cleaned, or awaiting cleanup")
+            task = await db.get(ReviewTask, session.review_task_id)
+            if task is None or task.completed_at is not None:
+                raise ReviewConflict("Session task is completed")
+            monitor = await db.get(PRMonitor, (task.account_id, task.pull_request_id))
+            if (
+                monitor is None
+                or monitor.task_id != task.id
+                or monitor.snapshot_json["state"] != "open"
+            ):
+                raise ReviewConflict("Session task is no longer current and open")
+            if not session.backend_session_id:
+                raise ReviewConflict(
+                    "No agent conversation was created. Request another review before resuming."
+                )
+            if await _background_owned(db, task.id):
+                raise ReviewConflict("Background work still owns this task")
+            if await db.scalar(select(LeaseModel.token).where(LeaseModel.session_id == session.id)):
+                raise ReviewConflict("Foreground process still owns this session")
+            lease = LeaseModel(
+                session_id=session.id,
+                backend_session_id=session.backend_session_id,
+                head_sha=str(monitor.snapshot_json["head_sha"]),
+                task_version=task.action_version,
+            )
+            db.add(lease)
+            session.status = "ready"
+            session.resumed_at = utc_now()
+            await db.flush()
+            result = ForegroundLease(
+                lease.token,
+                session.id,
+                lease.backend_session_id,
+                lease.head_sha,
+                lease.task_version,
+                lease.acquired_at,
+            )
+            await db.commit()
+            return result
+
+    async def release_foreground(self, token: UUID) -> None:
+        """Caller has established exit (or that launch never occurred), including descendants."""
+        async with self.database.sessions() as db:
+            await self._begin(db)
+            lease = await db.get(LeaseModel, token)
+            if lease is None:
+                raise ReviewConflict("Foreground lease does not exist")
+            session = await db.get(ReviewSession, lease.session_id)
+            assert session is not None
+            session.status = "suspended"
+            await db.delete(lease)
+            await db.commit()
+
+    async def claim_cleanup(self) -> CleanupClaim | None:
+        """Skip busy jobs; no timeout can steal ownership from a living process."""
+        async with self.database.sessions() as db:
+            await self._begin(db)
+            jobs = await db.scalars(
+                select(CleanupJob)
+                .where(
+                    CleanupJob.status.in_(("pending", "failed")),
+                    (CleanupJob.next_retry_at.is_(None)) | (CleanupJob.next_retry_at <= utc_now()),
+                )
+                .order_by(CleanupJob.created_at)
+            )
+            for job in jobs:
+                task = await db.get(ReviewTask, job.review_task_id)
+                if task is None or task.completed_at is None:
+                    continue
+                if await _background_owned(db, task.id):
+                    continue
+                foreground = await db.scalar(
+                    select(LeaseModel.token)
+                    .join(ReviewSession)
+                    .where(ReviewSession.review_task_id == task.id)
+                )
+                if foreground is not None:
+                    continue
+                sessions = tuple(
+                    await db.scalars(
+                        select(ReviewSession).where(
+                            ReviewSession.review_task_id == task.id,
+                            ReviewSession.status != "cleaned",
+                        )
+                    )
+                )
+                claim = ClaimModel(job_id=job.id)
+                db.add(claim)
+                job.status = "running"
+                job.attempts += 1
+                job.last_error = None
+                for session in sessions:
+                    session.cleanup_status = "running"
+                await db.flush()
+                result = CleanupClaim(
+                    claim.token,
+                    job.id,
+                    tuple(
+                        CleanupSession(
+                            session.id,
+                            session.reviewer_id,
+                            session.backend_session_id,
+                            session.transcript_ref,
+                            tuple(
+                                tuple(sorted(item.items()))
+                                for item in session.resource_manifest_json
+                            ),
+                        )
+                        for session in sessions
+                    ),
+                )
+                await db.commit()
+                return result
+            return None
+
+    async def finish_cleanup(self, token: UUID, *, succeeded: bool) -> None:
+        """Commit deletion evidence, or retain resources for an idempotent retry."""
+        async with self.database.sessions() as db:
+            await self._begin(db)
+            claim = await db.get(ClaimModel, token)
+            if claim is None:
+                raise ReviewConflict("Cleanup claim does not exist")
+            job = await db.get(CleanupJob, claim.job_id)
+            assert job is not None
+            sessions = await db.scalars(
+                select(ReviewSession).where(
+                    ReviewSession.review_task_id == job.review_task_id,
+                    ReviewSession.status != "cleaned",
+                )
+            )
+            for session in sessions:
+                session.cleanup_status = "succeeded" if succeeded else "failed"
+                if succeeded:
+                    session.status = "cleaned"
+                    session.cleaned_at = utc_now()
+                    session.backend_session_id = None
+                    session.transcript_ref = None
+                    session.resource_manifest_json = []
+            if succeeded:
+                runs = await db.scalars(
+                    select(AIRun).where(AIRun.review_task_id == job.review_task_id)
+                )
+                for run in runs:
+                    run.stdout_blob = run.stderr_blob = None
+                job.status = "succeeded"
+                job.completed_at = utc_now()
+                job.next_retry_at = None
+                job.last_error = None
+            else:
+                job.status = "failed"
+                job.last_error = "Session cleanup failed; resources retained for retry"
+                job.next_retry_at = utc_now() + timedelta(
+                    seconds=min(3600, 30 * 2 ** min(job.attempts, 7))
+                )
+            await db.delete(claim)
+            await db.commit()

diffbutler/store/migrations/__init__.py

@@ -0,0 +1 @@
+"""Packaged Alembic migrations."""

diffbutler/store/migrations/env.py

@@ -0,0 +1,14 @@
+"""Run migrations on the caller's connection, including async run_sync bridges."""
+
+from alembic import context
+
+from diffbutler.store.models import Base
+
+context.configure(
+    connection=context.config.attributes["connection"],
+    target_metadata=Base.metadata,
+    render_as_batch=True,
+    compare_type=True,
+)
+with context.begin_transaction():
+    context.run_migrations()