From d4e10e38b45cf4b8a6fcd599bcd6b87805e0aeb0 Mon Sep 17 00:00:00 2001 From: lilyplasticlabs Date: Fri, 17 Apr 2026 21:21:24 -0400 Subject: [PATCH] docs(dreamer): document explicit-only invariant on enqueue_dream.document_count Loop 3 follow-up on d76627a. The parameter's semantic tightened across Loop 2 (check_and_schedule_dream, execute_dream) and Loop 3 (schedule_dream route) to "explicit-level count, used as the baseline," but the signature still read "Current document count for metadata update." The next caller would have no way to know from the function contract. Docstring now spells out: (1) the value is explicit-only, (2) it's written as last_dream_document_count, (3) it's the baseline that check_and_schedule_dream subtracts from to compute documents_since_last_dream, (4) passing a count that includes non-explicit levels (deductive, inductive, contradiction) inflates the baseline and suppresses the next scheduled dream. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/deriver/enqueue.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/deriver/enqueue.py b/src/deriver/enqueue.py index d79350f2..fe0f3ab1 100644 --- a/src/deriver/enqueue.py +++ b/src/deriver/enqueue.py @@ -450,7 +450,13 @@ async def enqueue_dream( observer: Name of the observer peer observed: Name of the observed peer dream_type: Type of dream to execute - document_count: Current document count for metadata update + document_count: Count of explicit-level documents only. Written as + last_dream_document_count and used as the baseline that + dream_scheduler.check_and_schedule_dream subtracts from a future + explicit-filtered count to compute documents_since_last_dream. + Callers that include non-explicit levels (deductive, inductive, + contradiction) will inflate the baseline and suppress the next + scheduled dream. session_name: Name of the session to scope the dream to if specified """ async with tracked_db("dream_enqueue") as db_session: