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) <noreply@anthropic.com>
This commit is contained in:
lilyplasticlabs 2026-04-17 21:21:24 -04:00
parent d76627a8a4
commit d4e10e38b4
1 changed files with 7 additions and 1 deletions

View File

@ -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: