feat: NATS JetStream + Todoist background sync (#21, #22)

Issue 21 — event infrastructure:
- NormalizedEvent<T> + payload types in packages/shared-types/src/events/
- Bus.onPublish() hook for side-effect bridges
- NATS JetStream adapter (services/api/src/events/nats.ts): connects when
  NATS_URL is set, creates signals.> and feedback.> streams, bridges all
  in-process bus publishes to JetStream — no-ops gracefully when NATS is absent
- NATS service added to docker-compose (profile: events|full, port 4222/8222)

Issue 22 — Todoist background sync:
- services/api/src/signals/scheduler.ts: queries all active-token users every
  15 min (TODOIST_SYNC_INTERVAL_MS), fan-out via todoistSource.fetchSignals()
  which emits signals.task.synced; on-demand fetch remains as freshness fallback
- NATS_URL + TODOIST_SYNC_INTERVAL_MS added to config

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

services/api/src/events/bus.ts

@@ -69,6 +69,12 @@ const RING_SIZE = 500;
 class Bus extends EventEmitter {
   private ring: StoredEvent[] = [];
   private seq = 0;
+  private publishHooks: Array<(subject: string, payload: unknown) => void> = [];
+
+  /** Register a side-effect hook called on every publish (e.g. NATS bridge) */
+  onPublish(hook: (subject: string, payload: unknown) => void): void {
+    this.publishHooks.push(hook);
+  }
 
   publish<K extends keyof EventMap>(subject: K, payload: EventMap[K]): void {
     const entry: StoredEvent = {
@@ -80,6 +86,7 @@ class Bus extends EventEmitter {
     if (this.ring.length >= RING_SIZE) this.ring.shift();
     this.ring.push(entry);
     this.emit(subject, payload);
+    for (const hook of this.publishHooks) hook(subject, payload);
   }
 
   subscribe<K extends keyof EventMap>(subject: K, handler: (payload: EventMap[K]) => void): void {

services/api/src/events/nats.ts

@@ -0,0 +1,84 @@
+/**
+ * Optional NATS JetStream adapter.
+ *
+ * When NATS_URL is set: connects to NATS, creates the required streams on
+ * startup, and wraps the in-process Bus so every publish also goes to
+ * JetStream. Subscribers across processes (ml/serving, future services)
+ * consume from JetStream.
+ *
+ * When NATS_URL is not set: this module is a no-op and the in-process Bus
+ * works as before.
+ */
+
+import type { NatsConnection, JetStreamClient, StreamConfig } from 'nats';
+import { bus } from './bus.js';
+
+let nc: NatsConnection | null = null;
+let js: JetStreamClient | null = null;
+
+// nats enums are string enums — import the values at runtime, not just types
+async function getStreamConfigs(): Promise<Partial<StreamConfig>[]> {
+  const { StorageType: S, RetentionPolicy: R, DiscardPolicy: D } = await import('nats');
+  return [
+    {
+      name: 'signals',
+      subjects: ['signals.>'],
+      max_msgs: 500_000,
+      max_age: 7 * 24 * 60 * 60 * 1e9, // 7 days in nanoseconds
+      storage: S.File,
+      retention: R.Limits,
+      discard: D.Old,
+      num_replicas: 1,
+      duplicate_window: 120e9,
+    },
+    {
+      name: 'feedback',
+      subjects: ['feedback.>'],
+      max_msgs: 200_000,
+      max_age: 30 * 24 * 60 * 60 * 1e9,
+      storage: S.File,
+      retention: R.Limits,
+      discard: D.Old,
+      num_replicas: 1,
+      duplicate_window: 120e9,
+    },
+  ];
+}
+
+export async function connectNats(natsUrl: string): Promise<void> {
+  try {
+    const { connect } = await import('nats');
+    nc = await connect({ servers: natsUrl, reconnect: true, maxReconnectAttempts: -1 });
+    js = nc.jetstream();
+
+    // Ensure streams exist (idempotent)
+    const STREAMS = await getStreamConfigs();
+    const jsm = await nc.jetstreamManager();
+    for (const cfg of STREAMS) {
+      try {
+        await jsm.streams.info(cfg.name!);
+      } catch {
+        await jsm.streams.add(cfg as StreamConfig);
+      }
+    }
+
+    // Bridge: every in-process bus publish also goes to JetStream
+    bus.onPublish((subject, payload) => {
+      if (!js) return;
+      const data = new TextEncoder().encode(JSON.stringify(payload));
+      js.publish(subject, data).catch((err: Error) =>
+        console.error(`[nats] publish failed for ${subject}: ${err.message}`),
+      );
+    });
+
+    console.log(`[nats] connected to ${natsUrl}, streams: ${STREAMS.map((s) => s.name).join(', ')}`);
+  } catch (err: any) {
+    console.warn(`[nats] connection failed — running without JetStream: ${err.message}`);
+  }
+}
+
+export async function closeNats(): Promise<void> {
+  await nc?.drain();
+  nc = null;
+  js = null;
+}