waggle-os/docs/plans/DREAM-DIARY-2026-07-09.md

Dream Diary — "what I consolidated last night"

Date: 2026-07-09 · Status: approved (founder Q&A) · Branch: worktree-channels-arc Origin: CowAgent teardown steal #1 (docs/analysis/cowagent-vs-waggle-2026-07-09.md). Waggle already runs real nightly memory curation (compaction, harvest sync, index repair, lane extraction) but reports it only to log.info — the user never sees the substrate working. The diary narrates those real events. It must never fabricate.

Founder decisions (locked)

Decision	Choice
Narrative	Deterministic stats sentence always; LLM polish on top (built-in proxy fast tier). LLM down → deterministic stands.
Placement	Home cockpit card ("While you slept") + expandable 7-day history. Suppressed until the first dream exists.

Architecture

• packages/server/src/local/dream-journal.ts — DreamJournal: one JSON per day at <dataDir>/dreams/YYYY-MM-DD.json (atomic tmp+rename). record(action, stats) appends a structured event + recomputes the deterministic summary from aggregated day counters. Product layer on purpose — NOT hive-mind-core (no OSS port obligation).
• Event sources — the four existing memory_consolidation cron branches in local/index.ts: memory_compact (temporaryPruned/deprecatedPruned/pframesMerged), harvest_sync (frames/items/sources/couldNotVerify), index_reconcile (ftsFixed/vecFixed), memory_lane_extract (lane counters). Zero-count runs are recorded (honest "quiet night"). Failures are not diary events (already logged elsewhere).
• LLM polish — lazy: GET /api/dreams returns deterministic text immediately; if a day has events but no narrative, it schedules ONE guarded background polish call (in-flight set), persisted into the day file; next poll shows it. Zero-activity nights skip the LLM (cost).
• Route — routes/dreams.ts: GET /api/dreams?days=7 (isLocalRequest-guarded) → [{date, events, summary, narrative?}], newest first.
• UI — apps/web/src/components/os/home/DreamDiaryCard.tsx on HomeCockpit: moon icon, latest day's narrative (fallback summary), expandable previous days. Hidden when no data.

Tests

Journal: record/aggregate/summary wording, atomic persistence across instances, zero-night summary, date rollover. Route: shape, days clamp, lazy-polish single-flight, LLM-failure fallback (narrative stays absent, summary intact). Web: card renders narrative, falls back to summary, hides with no data, history expand.

Verification

npx tsc --noEmit -p packages/server/tsconfig.json · server vitest · apps/web vitest · web build.