chore: document project-wide soft delete pattern and add deleted_by column to all tables

devplacepy/services/devii/agentic/lessons.py

@@ -44,7 +44,12 @@ class LessonStore:
     def _ensure_indexes(self) -> None:
         if TABLE not in self._db.tables:
             return
-        self._db[TABLE].create_index(["owner_kind", "owner_id"])
+        table = self._db[TABLE]
+        if not table.has_column("deleted_at"):
+            table.create_column_by_example("deleted_at", "")
+        if not table.has_column("deleted_by"):
+            table.create_column_by_example("deleted_by", "")
+        table.create_index(["owner_kind", "owner_id"])
 
     @property
     def _table(self) -> Any:
@@ -57,7 +62,7 @@ class LessonStore:
     def count(self) -> int:
         if TABLE not in self._db.tables:
             return 0
-        return self._table.count(**self._scope)
+        return self._table.count(deleted_at=None, **self._scope)
 
     def add(
         self, observation: str, conclusion: str, next_action: str, tags: str = ""
@@ -70,6 +75,8 @@ class LessonStore:
             "tags": tags,
             "created_at": to_iso(now_utc()),
             "hits": 0,
+            "deleted_at": None,
+            "deleted_by": None,
             **self._scope,
         }
         self._table.insert(record)
@@ -82,14 +89,24 @@ class LessonStore:
     def all(self) -> list[dict[str, Any]]:
         if TABLE not in self._db.tables:
             return []
-        return list(self._table.find(**self._scope))
+        return list(self._table.find(deleted_at=None, **self._scope))
 
     def delete(self, uid: str) -> bool:
         if TABLE not in self._db.tables:
             return False
-        deleted = self._table.delete(uid=uid, **self._scope)
+        row = self._table.find_one(uid=uid, deleted_at=None, **self._scope)
+        if not row:
+            return False
+        self._table.update(
+            {
+                "id": row["id"],
+                "deleted_at": to_iso(now_utc()),
+                "deleted_by": f"{self._owner_kind}:{self._owner_id}",
+            },
+            ["id"],
+        )
         self._dirty = True
-        return bool(deleted)
+        return True
 
     def clear(self) -> int:
         n = self.count()