diff --git a/cases.py b/cases.py
new file mode 100644
index 0000000..03863f6
--- /dev/null
+++ b/cases.py
@@ -0,0 +1,111 @@
+"""Case store for the unsubscribe agent: one case per mail in the collection mailbox (SQLite)."""
+
+import hashlib
+import json
+import sqlite3
+import threading
+import time
+
+STATES = ("new", "running", "unsubscribed", "not_possible", "unclear")
+
+
+def case_key(message) -> str:
+ """Message-ID of the mail in the collection mailbox; the UID changes when the mail is moved."""
+ mid = (message.get("Message-ID") or "").strip()
+ if mid:
+ return mid
+ raw = "|".join(str(message.get(h, "")) for h in ("Date", "Subject", "From"))
+ return "sha256:" + hashlib.sha256(raw.encode("utf-8", "replace")).hexdigest()
+
+
+class CaseStore:
+ def __init__(self, path: str):
+ self._db = sqlite3.connect(path, check_same_thread=False)
+ self._db.row_factory = sqlite3.Row
+ self._lock = threading.Lock()
+ with self._lock, self._db:
+ self._db.execute(
+ "CREATE TABLE IF NOT EXISTS cases ("
+ "key TEXT PRIMARY KEY, subject TEXT NOT NULL, links TEXT NOT NULL, address TEXT NOT NULL, "
+ "state TEXT NOT NULL, reason TEXT NOT NULL DEFAULT '', evidence TEXT NOT NULL DEFAULT '', "
+ "evidence_url TEXT NOT NULL DEFAULT '', attempts INTEGER NOT NULL DEFAULT 0, "
+ "moved INTEGER NOT NULL DEFAULT 0, created_at REAL NOT NULL, updated_at REAL NOT NULL)"
+ )
+ self._db.execute("CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL)")
+
+ def _run(self, sql: str, args=()) -> int:
+ with self._lock, self._db:
+ return self._db.execute(sql, args).rowcount
+
+ def _rows(self, sql: str, args=()) -> list[dict]:
+ with self._lock:
+ rows = self._db.execute(sql, args).fetchall()
+ out = []
+ for r in rows:
+ d = dict(r)
+ d["links"] = json.loads(d["links"])
+ out.append(d)
+ return out
+
+ def add(self, key: str, subject: str, links: list[str], address: str) -> bool:
+ now = time.time()
+ return self._run(
+ "INSERT OR IGNORE INTO cases (key, subject, links, address, state, created_at, updated_at) "
+ "VALUES (?, ?, ?, ?, 'new', ?, ?)", (key, subject, json.dumps(links), address, now, now)) == 1
+
+ def get(self, key: str) -> dict | None:
+ rows = self._rows("SELECT * FROM cases WHERE key = ?", (key,))
+ return rows[0] if rows else None
+
+ def all(self) -> list[dict]:
+ return self._rows("SELECT * FROM cases ORDER BY created_at DESC, key")
+
+ def pending(self, limit: int) -> list[dict]:
+ return self._rows(
+ "SELECT * FROM cases WHERE state = 'new' AND attempts = 0 ORDER BY created_at, rowid LIMIT ?", (limit,))
+
+ def claim(self, key: str) -> None:
+ self._run("UPDATE cases SET state = 'running', attempts = attempts + 1, updated_at = ? WHERE key = ?",
+ (time.time(), key))
+
+ def release(self, key: str) -> None:
+ """Give a claimed case back without counting the attempt (agent or model was unavailable)."""
+ self._run("UPDATE cases SET state = 'new', attempts = MAX(attempts - 1, 0), updated_at = ? "
+ "WHERE key = ? AND state = 'running'", (time.time(), key))
+
+ def finish(self, key: str, state: str, reason: str = "", evidence: str = "", evidence_url: str = "") -> None:
+ if state not in ("unsubscribed", "not_possible", "unclear"):
+ raise ValueError(f"not a final state: {state}")
+ self._run("UPDATE cases SET state = ?, reason = ?, evidence = ?, evidence_url = ?, updated_at = ? "
+ "WHERE key = ?", (state, reason, evidence, evidence_url, time.time(), key))
+
+ def to_move(self) -> list[dict]:
+ return self._rows("SELECT * FROM cases WHERE state = 'unsubscribed' AND moved = 0 ORDER BY created_at")
+
+ def mark_moved(self, key: str) -> None:
+ self._run("UPDATE cases SET moved = 1 WHERE key = ?", (key,))
+
+ def retry(self, key: str) -> None:
+ self._run("UPDATE cases SET state = 'new', attempts = 0, reason = '', evidence = '', evidence_url = '', "
+ "updated_at = ? WHERE key = ? AND state IN ('not_possible', 'unclear')", (time.time(), key))
+
+ def expired(self, days: int, now: float | None = None) -> list[dict]:
+ limit = (now if now is not None else time.time()) - days * 86400
+ return self._rows("SELECT * FROM cases WHERE state = 'unsubscribed' AND moved = 1 AND updated_at < ? "
+ "ORDER BY created_at, rowid", (limit,))
+
+ def delete(self, key: str) -> None:
+ self._run("DELETE FROM cases WHERE key = ?", (key,))
+
+ def recover(self) -> int:
+ """Cases left in 'running' by a restart count as a used attempt."""
+ return self._run("UPDATE cases SET state = 'unclear', reason = 'interrupted by restart', updated_at = ? "
+ "WHERE state = 'running'", (time.time(),))
+
+ def meta(self, k: str, default: str = "") -> str:
+ with self._lock:
+ row = self._db.execute("SELECT v FROM meta WHERE k = ?", (k,)).fetchone()
+ return row["v"] if row else default
+
+ def set_meta(self, k: str, v: str) -> None:
+ self._run("INSERT INTO meta (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v", (k, v))
diff --git a/tests/test_cases.py b/tests/test_cases.py
new file mode 100644
index 0000000..f7d65fa
--- /dev/null
+++ b/tests/test_cases.py
@@ -0,0 +1,113 @@
+"""Case store: one case per forwarded mail, keyed by Message-ID."""
+
+from email.message import EmailMessage
+
+import pytest
+
+from cases import CaseStore, case_key
+
+
+@pytest.fixture
+def store(tmp_path):
+ return CaseStore(str(tmp_path / "cases.db"))
+
+
+def _msg(mid="", subject="News"):
+ m = EmailMessage()
+ if mid:
+ m["Message-ID"] = mid
+ m["Subject"] = subject
+ m["Date"] = "Sat, 14 Nov 2026 10:00:00 +0100"
+ m["From"] = "philipp@wagnersnetz.de"
+ return m
+
+
+def test_key_is_message_id_or_stable_hash():
+ assert case_key(_msg("")) == ""
+ k = case_key(_msg(""))
+ assert k.startswith("sha256:") and k == case_key(_msg("")) and k != case_key(_msg("", "Other"))
+
+
+def test_add_is_idempotent_and_keeps_links(store):
+ assert store.add("", "News", ["https://e.org/u1", "https://e.org/u2"], "p@wagnersnetz.de") is True
+ assert store.add("", "changed", [], "") is False
+ c = store.get("")
+ assert (c["subject"], c["links"], c["address"], c["state"], c["attempts"], c["moved"]) == (
+ "News", ["https://e.org/u1", "https://e.org/u2"], "p@wagnersnetz.de", "new", 0, 0)
+
+
+def test_pending_only_untried_new_cases_oldest_first(store):
+ for k in ("<1>", "<2>", "<3>"):
+ store.add(k, k, ["https://e.org"], "")
+ store.claim("<1>")
+ store.finish("<1>", "unclear", "x")
+ assert [c["key"] for c in store.pending(10)] == ["<2>", "<3>"]
+ assert [c["key"] for c in store.pending(1)] == ["<2>"]
+
+
+def test_claim_counts_attempt_and_release_gives_it_back(store):
+ store.add("<1>", "s", ["https://e.org"], "")
+ store.claim("<1>")
+ assert (store.get("<1>")["state"], store.get("<1>")["attempts"]) == ("running", 1)
+ store.release("<1>")
+ assert (store.get("<1>")["state"], store.get("<1>")["attempts"]) == ("new", 0)
+ assert [c["key"] for c in store.pending(10)] == ["<1>"]
+
+
+def test_finish_stores_reason_and_evidence(store):
+ store.add("<1>", "s", ["https://e.org"], "")
+ store.claim("<1>")
+ store.finish("<1>", "unsubscribed", "page confirms", "You have been unsubscribed", "https://e.org/done")
+ c = store.get("<1>")
+ assert (c["state"], c["reason"], c["evidence"], c["evidence_url"]) == (
+ "unsubscribed", "page confirms", "You have been unsubscribed", "https://e.org/done")
+ with pytest.raises(ValueError):
+ store.finish("<1>", "great", "")
+
+
+def test_to_move_and_mark_moved(store):
+ store.add("<1>", "s", ["https://e.org"], "")
+ store.claim("<1>")
+ store.finish("<1>", "unsubscribed")
+ assert [c["key"] for c in store.to_move()] == ["<1>"]
+ store.mark_moved("<1>")
+ assert store.to_move() == []
+
+
+def test_retry_makes_a_failed_case_pending_again(store):
+ store.add("<1>", "s", ["https://e.org"], "")
+ store.claim("<1>")
+ store.finish("<1>", "not_possible", "login")
+ store.retry("<1>")
+ c = store.get("<1>")
+ assert (c["state"], c["attempts"], c["reason"]) == ("new", 0, "")
+
+
+def test_expired_only_moved_successes_older_than_days(store):
+ for k in ("", "", ""):
+ store.add(k, "s", ["https://e.org"], "")
+ store.claim(k)
+ store.finish("", "unsubscribed")
+ store.finish("", "unsubscribed")
+ store.finish("", "unclear")
+ store.mark_moved("")
+ store.mark_moved("")
+ now = store.get("")["updated_at"]
+ assert [c["key"] for c in store.expired(30, now=now + 31 * 86400)] == ["", ""]
+ assert store.expired(30, now=now + 29 * 86400) == []
+ store.delete("")
+ assert store.get("") is None
+
+
+def test_recover_turns_running_into_unclear(store):
+ store.add("<1>", "s", ["https://e.org"], "")
+ store.claim("<1>")
+ assert store.recover() == 1
+ c = store.get("<1>")
+ assert (c["state"], c["reason"], c["attempts"]) == ("unclear", "interrupted by restart", 1)
+
+
+def test_meta_roundtrip(store):
+ assert store.meta("paused", "0") == "0"
+ store.set_meta("paused", "1")
+ assert store.meta("paused") == "1"