# 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.