From 183e53656ee7920ddd6795c61b3ddcd18e224f8e Mon Sep 17 00:00:00 2001
From: Kshitij Kapoor <82637225+kshitijk4poor@users.noreply.github.com>
Date: Sun, 23 Aug 2026 13:23:02 +0530
Subject: [PATCH] docs: make the mutate-then-persist marker contract explicit
 (#92231 review)

Reviewer point on #92539: nothing documented that an in-place content
mutation of a stamped dict must pop _DB_PERSISTED_MARKER (and invalidate
the bounded flush-scan prefix) or the DB silently goes stale. Both
existing mutators (turn_finalizer fill-empty-tail, context_compressor
micro-compaction defrag) already follow the contract; this states it at
the constant so the next one does too.
---
 run_agent.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/run_agent.py b/run_agent.py
index 6704ad7cbd..5da066ab18 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -276,6 +276,15 @@ _MAX_TOOL_WORKERS = 8
 # (agent/transports/chat_completions.py, agent/chat_completion_helpers.py) strip
 # every top-level ``_``-prefixed key before the request leaves the process, so
 # this never reaches a strict OpenAI-compatible gateway.
+#
+# CONTRACT (#92231): the marker asserts "this dict's CONTENT is durable as
+# written". Loaded rows are stamped at materialization time
+# (hermes_state._rows_to_conversation), so any code that mutates a loaded or
+# flushed dict's content in place and needs the change persisted MUST pop the
+# marker (and invalidate _db_flush_scan_prefix if the dict may sit inside the
+# bounded-scan prefix) — see agent/turn_finalizer.py (fill-empty-tail) and
+# agent/context_compressor.py (micro-compaction defrag) for the two canonical
+# pop sites. Mutating without popping leaves the DB silently stale.
 _DB_PERSISTED_MARKER = "_db_persisted"