feat: events journal write primitives (log_event, backfill, get_events_journal)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

hbd/server/journal.py

@@ -11,7 +11,7 @@ import os
 import asyncio
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, Any, Optional
+from typing import Dict, Any, Optional, Callable, Iterable, List, Tuple, Union
 
 logger = logging.getLogger(__name__)
 
@@ -149,10 +149,35 @@ class MessageJournal:
                     self._current_size += len(json_bytes)
                     
                     logger.debug(f"Logged message from {addr[0]}: {msg.get('ID', 'UNKNOWN')}")
-                    
+
             except Exception as e:
                 logger.error(f"Error writing to journal: {e}")
-    
+
+    async def log_event(self, event: Dict[str, Any]):
+        """Write a caller-provided dict verbatim as one JSONL line (with rotation)."""
+        if not self.enabled or not self._initialized:
+            return
+        async with self._lock:
+            try:
+                line = json.dumps(event, separators=(',', ':')) + '\n'
+                nbytes = len(line.encode('utf-8'))
+                if self._current_size + nbytes > self.max_size:
+                    await self._rotate()
+                if self._file_handle:
+                    self._file_handle.write(line)
+                    self._file_handle.flush()
+                    self._current_size += nbytes
+            except Exception as e:
+                logger.error(f"Error writing event to journal: {e}")
+
+    async def backfill(self, events: Iterable[Dict[str, Any]]):
+        """One-time seed: write *events* only if the journal file is currently empty."""
+        if not self.enabled or not self._initialized or self._current_size > 0:
+            return
+        for ev in events:
+            if isinstance(ev, dict):
+                await self.log_event(ev)
+
     async def _rotate(self):
         """
         Rotate the journal file.
@@ -332,7 +357,7 @@ def get_journal(config: Optional[Dict[str, Any]] = None) -> MessageJournal:
 async def log_message(msg: Dict[str, Any], addr: tuple, timestamp: Optional[float] = None):
     """
     Convenience function to log a message using the global journal.
-    
+
     Args:
         msg: Parsed message dictionary
         addr: Source address (ip, port) tuple
@@ -340,3 +365,28 @@ async def log_message(msg: Dict[str, Any], addr: tuple, timestamp: Optional[floa
     """
     journal = get_journal()
     await journal.log_message(msg, addr, timestamp)
+
+
+# Global events journal instance (human-readable event log, written by notify.eventlog)
+_events_journal_instance: Optional[MessageJournal] = None
+
+
+def get_events_journal(config: Optional[Dict[str, Any]] = None) -> MessageJournal:
+    """Get or create the global events journal instance.
+
+    Uses the events_journal_* config keys; shares journal_dir and
+    journal_enabled with the raw-datagram journal.
+    """
+    global _events_journal_instance
+    if _events_journal_instance is None:
+        cfg = config or {}
+        _events_journal_instance = MessageJournal(
+            {
+                'journal_dir': cfg.get('journal_dir', '/var/log/heartbeat'),
+                'journal_file': cfg.get('events_journal_file', 'events.journal'),
+                'journal_max_size': cfg.get('events_journal_max_size', 10 * 1024 * 1024),
+                'journal_max_backups': cfg.get('events_journal_max_backups', 10),
+                'journal_enabled': cfg.get('journal_enabled', True),
+            }
+        )
+    return _events_journal_instance