feat: improve resume optimization and import reliability

backend/app/database.py

@@ -17,6 +17,10 @@ from .models import (
 )
 
 
+class SessionRevisionConflict(Exception):
+    """The session changed after a caller captured its processing snapshot."""
+
+
 def utc_now() -> str:
     return datetime.now(UTC).isoformat()
 
@@ -230,6 +234,7 @@ class Database:
         draft_id: str | None = None,
         resume_id: str | None = None,
         increment_revision: bool = True,
+        expected_revision: int | None = None,
     ) -> dict[str, Any]:
         current = self.fetch_session(connection, session_id)
         if current is None:
@@ -237,21 +242,30 @@ class Database:
         revision = current["revision"] + (1 if increment_revision else 0)
         draft_value = draft_id if draft_id is not None else current["draft_id"]
         resume_value = resume_id if resume_id is not None else current["resume_id"]
-        connection.execute(
+        where = "id = ?"
+        parameters: list[Any] = [
+            stage,
+            revision,
+            json.dumps(profile, ensure_ascii=False),
+            draft_value,
+            resume_value,
+            utc_now(),
+            session_id,
+        ]
+        if expected_revision is not None:
+            where += " AND revision = ?"
+            parameters.append(expected_revision)
+        cursor = connection.execute(
             """UPDATE sessions
                SET stage = ?, revision = ?, profile_json = ?, draft_id = ?,
                    resume_id = ?, updated_at = ?
-               WHERE id = ?""",
-            (
-                stage,
-                revision,
-                json.dumps(profile, ensure_ascii=False),
-                draft_value,
-                resume_value,
-                utc_now(),
-                session_id,
-            ),
+               WHERE """ + where,
+            parameters,
         )
+        if cursor.rowcount != 1:
+            if self.fetch_session(connection, session_id) is None:
+                raise KeyError(session_id)
+            raise SessionRevisionConflict(session_id)
         updated = self.fetch_session(connection, session_id)
         assert updated is not None
         return updated
@@ -318,19 +332,25 @@ class Database:
         *,
         lifecycle: str,
         data: dict[str, Any] | None = None,
+        expected_version: int | None = None,
     ) -> None:
         row = connection.execute(
-            "SELECT data_json FROM blocks WHERE id = ?", (block_id,)
+            "SELECT data_json, version FROM blocks WHERE id = ?", (block_id,)
         ).fetchone()
         if row is None:
             raise KeyError(block_id)
         serialized = row["data_json"] if data is None else json.dumps(data, ensure_ascii=False)
-        connection.execute(
+        statement = (
             """UPDATE blocks
                SET lifecycle = ?, data_json = ?, version = version + 1, updated_at = ?
-               WHERE id = ?""",
-            (lifecycle, serialized, utc_now(), block_id),
+               WHERE id = ?"""
         )
+        parameters: list[Any] = [lifecycle, serialized, utc_now(), block_id]
+        if expected_version is not None:
+            statement += " AND version = ?"
+            parameters.append(expected_version)
+        if connection.execute(statement, parameters).rowcount != 1:
+            raise SessionRevisionConflict(block_id)
 
     def supersede_active_components(
         self,
@@ -415,8 +435,9 @@ class Database:
         )
 
     def fetch_resume(
-        self, connection: sqlite3.Connection, session_id: str
+        self, connection: sqlite3.Connection, session_id: str, *, for_update: bool = False
     ) -> dict[str, Any] | None:
+        del for_update
         row = connection.execute(
             "SELECT * FROM resumes WHERE session_id = ?", (session_id,)
         ).fetchone()
@@ -458,16 +479,27 @@ class Database:
         connection: sqlite3.Connection,
         session_id: str,
         content: dict[str, Any],
+        *,
+        expected_revision: int | None = None,
     ) -> dict[str, Any]:
-        connection.execute(
+        statement = (
             """UPDATE resumes
                SET revision = revision + 1, content_json = ?, updated_at = ?
-               WHERE session_id = ?""",
-            (json.dumps(content, ensure_ascii=False), utc_now(), session_id),
+               WHERE session_id = ?"""
         )
-        result = self.fetch_resume(connection, session_id)
-        if result is None:
+        values: tuple[Any, ...] = (
+            json.dumps(content, ensure_ascii=False), utc_now(), session_id
+        )
+        if expected_revision is not None:
+            statement += " AND revision = ?"
+            values += (expected_revision,)
+        result = connection.execute(statement, values)
+        if result.rowcount != 1:
+            if expected_revision is not None:
+                raise SessionRevisionConflict(session_id)
             raise KeyError(session_id)
+        result = self.fetch_resume(connection, session_id)
+        assert result is not None
         return result
 
     def create_optimization_run(