From d592a98452a60682db67c38bedfedcc282b222aa Mon Sep 17 00:00:00 2001 From: rayhpeng Date: Mon, 6 Apr 2026 11:24:29 +0800 Subject: [PATCH] docs: annotate DbRunEventStore.put() as low-frequency path Add docstring clarifying that put() opens a per-call transaction with FOR UPDATE and should only be used for infrequent writes (currently just the initial human_message event). High-throughput callers should use put_batch() instead. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../harness/deerflow/runtime/events/store/db.py | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/backend/packages/harness/deerflow/runtime/events/store/db.py b/backend/packages/harness/deerflow/runtime/events/store/db.py index 26463bf7b..0502cd879 100644 --- a/backend/packages/harness/deerflow/runtime/events/store/db.py +++ b/backend/packages/harness/deerflow/runtime/events/store/db.py @@ -53,7 +53,15 @@ class DbRunEventStore(RunEventStore): metadata = {**(metadata or {}), "content_truncated": True, "original_byte_length": len(encoded)} return content, metadata or {} - async def put(self, *, thread_id, run_id, event_type, category, content="", metadata=None, created_at=None): + async def put(self, *, thread_id, run_id, event_type, category, content="", metadata=None, created_at=None): # noqa: D401 + """Write a single event — low-frequency path only. + + This opens a dedicated transaction with a FOR UPDATE lock to + assign a monotonic *seq*. For high-throughput writes use + :meth:`put_batch`, which acquires the lock once for the whole + batch. Currently the only caller is ``worker.run_agent`` for + the initial ``human_message`` event (once per run). + """ content, metadata = self._truncate_trace(category, content, metadata) if isinstance(content, dict): db_content = json.dumps(content, default=str, ensure_ascii=False)