From 6351d60a6f3ae2b699ada9e59e26136306ec7c58 Mon Sep 17 00:00:00 2001
From: kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Tue, 22 Sep 2026 15:17:12 +0530
Subject: [PATCH] docs(gateway): point the rich_sent_store restatements at
 _LOCK

The "atomic write != atomic load/merge/save triple" rationale was stated
three times in our text.  The canonical statement stays on
`rich_sent_store._LOCK`; the inline `_update` comment and the
`test_concurrent_record_async_calls_lose_no_entry` docstring now
reference it in one line each.  Behaviour-neutral: comments and a
docstring only.

PROOF: `git diff HEAD~1 --stat` touches 2 files, no code lines; ruff
clean; `import gateway.rich_sent_store` ok; scripts/run_tests.sh
tests/gateway/test_rich_sent_store_off_loop.py green.  The
sticker_cache.py async docstring and both off-loop test-module
docstrings are blame-attributed to contributor commits 4a77e841d4 /
1642d6a093 and were left untouched per the fold rule; the
helpers.py:116-127 two-lock comment is the canonical tracker statement
and was kept.
---
 gateway/rich_sent_store.py                     | 2 +-
 tests/gateway/test_rich_sent_store_off_loop.py | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/gateway/rich_sent_store.py b/gateway/rich_sent_store.py
index 00ae6e471a..4cb54129bf 100644
--- a/gateway/rich_sent_store.py
+++ b/gateway/rich_sent_store.py
@@ -57,7 +57,7 @@ def _update(chat_id, message_id, fields: dict) -> None:
             if len(data) > _MAX_ENTRIES:  # trim oldest by timestamp
                 for k, _ in sorted(data.items(), key=lambda kv: kv[1].get("ts", 0))[: len(data) - _MAX_ENTRIES]:
                     data.pop(k, None)
-            atomic_json_write(path, data, indent=None)  # atomic write; the lock makes the triple atomic
+            atomic_json_write(path, data, indent=None)  # see _LOCK
         except Exception:
             return
 
diff --git a/tests/gateway/test_rich_sent_store_off_loop.py b/tests/gateway/test_rich_sent_store_off_loop.py
index 16b5a0a5ad..f713a1befd 100644
--- a/tests/gateway/test_rich_sent_store_off_loop.py
+++ b/tests/gateway/test_rich_sent_store_off_loop.py
@@ -36,9 +36,8 @@ def test_record_async_runs_off_the_loop_thread(isolated_store, monkeypatch):
 def test_concurrent_record_async_calls_lose_no_entry(isolated_store, monkeypatch):
     """Two off-loop RMWs for different keys must both land in the durable file.
 
-    ``atomic_json_write`` makes each write atomic, not load/merge/save. Slowing the
-    write forces the second caller to load the same pre-state unless ``_update`` is
-    serialized, in which case the later ``os.replace`` drops the other key.
+    Slowing the write forces the lost-update race described on
+    ``rich_sent_store._LOCK`` unless ``_update`` is serialized.
     """
     real_write = rich_sent_store.atomic_json_write