refactor(agent/E_session): by-hand docstring/comment compaction across 9 files; transcript_repair row lookup helper; activity snapshot literal

agent/transcript_repair.py

@@ -1,7 +1,6 @@
-"""Transcript repair for SessionDB batch appends: reconcile in-memory assistant
-rows with committed SQLite rows (blank-row in-place update, concurrent-winner
-adoption, watermark-compaction clone lookup) and sync markers after commit.
-"""
+"""Transcript repair for SessionDB batch appends: reconcile in-memory assistant rows with committed SQLite
+rows (blank-row in-place update, concurrent-winner adoption, watermark-compaction clone lookup) and sync
+markers after commit."""
 
 from __future__ import annotations
 
@@ -18,11 +17,7 @@ def is_content_blank(content: Any) -> bool:
     if isinstance(content, str):
         return not content.strip()
     if isinstance(content, list):
-        if not content:
-            return True
-        return not "".join(
-            p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text"
-        ).strip()
+        return not "".join(p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text").strip()
     return False
 
 
@@ -33,54 +28,54 @@ def resolve_and_repair_transcript_batch(
     encode_content_fn: Callable[[Any], Any],
     decode_content_fn: Callable[[Any], Any],
 ) -> List[Dict[str, Any]]:
-    """Partition a message batch within an active write transaction.
-
-    An assistant message carrying an existing integer ``_row_id`` targets its active SQLite row (or
-    the active clone a watermark compaction made of it): a blank row is updated in place; a
-    non-blank one (concurrent winner) has its canonical content adopted without overwrite.
-    Returns the messages that must be inserted as fresh rows.
-    """
+    """Partition a message batch within an active write transaction. An assistant message carrying an
+    existing integer ``_row_id`` targets its active SQLite row (or the active clone a watermark compaction
+    made of it): a blank row is updated in place; a non-blank one (concurrent winner) has its canonical
+    content adopted without overwrite. Returns the messages that must be inserted as fresh rows."""
     inserted_rows: List[Dict[str, Any]] = []
     for msg in messages:
-        repaired = False
         existing_row_id = msg.get("_row_id") if isinstance(msg, dict) else None
+        target_row = None
         if isinstance(existing_row_id, int) and msg.get("role", "unknown") == "assistant":
-            row = conn.execute(
-                "SELECT id, role, active, timestamp, content FROM messages "
-                "WHERE id = ? AND session_id = ?",
-                (existing_row_id, session_id),
-            ).fetchone()
-            target_row = None
-            if row is not None and row["role"] == "assistant":
-                if int(row["active"] or 0) == 1:
-                    target_row = row
-                else:
-                    # Watermark compaction soft-archived the concurrent tail and cloned it.
-                    target_row = conn.execute(
-                        "SELECT id, role, active, timestamp, content FROM messages "
-                        "WHERE session_id = ? AND active = 1 AND role = 'assistant' "
-                        "AND timestamp IS ? AND id != ? "
-                        "ORDER BY id DESC LIMIT 1",
-                        (session_id, row["timestamp"], row["id"]),
-                    ).fetchone()
-            if target_row is not None:
-                target_id = int(target_row["id"])
-                decoded = decode_content_fn(target_row["content"])
-                msg["_row_id"] = target_id
-                if is_content_blank(decoded):
-                    conn.execute(
-                        "UPDATE messages SET content = ? "
-                        "WHERE id = ? AND session_id = ? AND active = 1",
-                        (encode_content_fn(msg.get("content")), target_id, session_id),
-                    )
-                else:
-                    msg["_canonical_content"] = decoded  # concurrent winner: adopt, don't overwrite
-                repaired = True
-        if not repaired:
+            target_row = _active_assistant_row(conn, session_id, existing_row_id)
+        if target_row is None:
             inserted_rows.append(msg)
+            continue
+        target_id = int(target_row["id"])
+        decoded = decode_content_fn(target_row["content"])
+        msg["_row_id"] = target_id
+        if is_content_blank(decoded):
+            conn.execute(
+                "UPDATE messages SET content = ? "
+                "WHERE id = ? AND session_id = ? AND active = 1",
+                (encode_content_fn(msg.get("content")), target_id, session_id),
+            )
+        else:
+            msg["_canonical_content"] = decoded  # concurrent winner: adopt, don't overwrite
     return inserted_rows
 
 
+def _active_assistant_row(conn: sqlite3.Connection, session_id: str, row_id: int):
+    """The active assistant row for ``row_id``, or the active clone a watermark compaction made of it."""
+    row = conn.execute(
+        "SELECT id, role, active, timestamp, content FROM messages "
+        "WHERE id = ? AND session_id = ?",
+        (row_id, session_id),
+    ).fetchone()
+    if row is None or row["role"] != "assistant":
+        return None
+    if int(row["active"] or 0) == 1:
+        return row
+    # Watermark compaction soft-archived the concurrent tail and cloned it.
+    return conn.execute(
+        "SELECT id, role, active, timestamp, content FROM messages "
+        "WHERE session_id = ? AND active = 1 AND role = 'assistant' "
+        "AND timestamp IS ? AND id != ? "
+        "ORDER BY id DESC LIMIT 1",
+        (session_id, row["timestamp"], row["id"]),
+    ).fetchone()
+
+
 def sync_flushed_message_markers(batch_msgs: List[Dict[str, Any]], batch_rows: List[Dict[str, Any]]) -> None:
     """Stamp _DB_PERSISTED_MARKER and sync canonical row ID / content onto live dicts after commit."""
     for written, row in zip(batch_msgs, batch_rows):