refactor(docs): split notification system docs into plan and implementation

Replace monolithic notification-system-implementation-plan.md with focused strategic plan (notification-system-plan.md) and detailed implementation guide (notification-system-implementation.md). Both documents now perfectly aligned with TimeSafari codebase patterns including: - Actual Settings type extension pattern (JSON strings for complex objects) - Real useNotifications composable stub signatures with eslint-disable - Verified logger exports and safeStringify usage - Confirmed PlatformServiceMixin.$saveSettings integration - Validated migration system registerMigration patterns Documents are production-ready with accurate code examples verified against actual TimeSafari infrastructure.
2 weeks ago · cfeb920493
3 changed files with 2329 additions and 644 deletions
--- a/doc/notification-system-implementation-plan.md
+++ b/doc/notification-system-implementation-plan.md
@ -1,644 +0,0 @@
 # TimeSafari Notification System — Feature-First Execution Pack
 **Author**: Matthew Raymer  
 **Date**: 2025-01-27T15:00Z (UTC)  
 **Status**: 🚀 **ACTIVE** - Surgical PR implementation for Capacitor platforms
 ## Purpose
 We **will deliver** 1..M daily local notifications with content fetched beforehand so they **will display offline**. We **will support** online-first (API→DB→Schedule) with offline-first fallback. New v1 ships in-app; New v2 extracts to a native Capacitor plugin with the same API.
 ## What we'll ship (v1 in-app)
 - **Multi-daily one-shot local notifications** (rolling window; today + tomorrow within iOS pending limits ~64)
 - **Online-first** content fetch (**ETag**, 10–15s timeout) with **offline-first** fallback and **TTL** handling ("(cached)" or skip)
 - **SQLite persistence** (contents, deliveries, config) with **14-day retention**
 - **Templating**: `{title, body}` with `{{var}}` substitution **before** scheduling
 - **Event queue** in SQLite: `delivery`, `error`, `heartbeat`; **drain on foreground**
 - **Resilience hooks**: re-arm on **app resume**, and when **timezone/offset** changes
 ---
 ## New v2 (Plugin) — What It Adds
 - **Native schedulers** (WorkManager+AlarmManager / BGTask+UNUserNotificationCenter) incl. exact/inexact handling
 - **Native HTTP** + **native SQLite** for reliability/perf
 - **Server-assist (silent push)** to wake at T-lead and prefetch
 - **Same TS API**, adapters swapped
 ---
 ## Feature Flags
 - `scheduler: 'capacitor'|'native'`
 - `mode: 'online-first'|'offline-first'|'auto'`
 - `prefetchLeadMinutes`, `ttlSeconds`
 ---
 ## Minimal PR layout
 ```
 /src/services/notifs/
  types.ts
  NotificationOrchestrator.ts
  adapters/
    DataStoreSqlite.ts
    SchedulerCapacitor.ts
    CallbacksHttp.ts
 /migrations/
  00XX_notifs.sql
 /sw_scripts/
  notification-click.js   # (or merge into sw_scripts-combined.js)
 /app/bootstrap/
  notifications.ts        # init + feature flags
 ```
 ---
 ## Changes (surgical)
 /src/services/notifs/
  types.ts
  NotificationOrchestrator.ts
  adapters/
    DataStoreSqlite.ts
    SchedulerCapacitor.ts
    CallbacksHttp.ts
 /migrations/
  00XX_notifs.sql
 /sw_scripts/
  notification-click.js   # (or merge into sw_scripts-combined.js)
 /app/bootstrap/
  notifications.ts        # init + feature flags
 ```
 ---
 ## Changes (surgical)
 ### 1) Dependencies
 ```bash
 npm i @capacitor/local-notifications
 npx cap sync
 ```
 ### 2) Capacitor setup
 ```typescript
 // capacitor.config.ts
 plugins: {
  LocalNotifications: {
    smallIcon: 'ic_stat_name',
    iconColor: '#4a90e2'
  }
 }
 ```
 ### 3) Android channel + iOS category (once at app start)
 ```typescript
 import { LocalNotifications } from '@capacitor/local-notifications';
 export async function initNotifChannels() {
  await LocalNotifications.createChannel({
    id: 'timesafari.daily',
    name: 'TimeSafari Daily',
    description: 'Daily briefings',
    importance: 4, // high
  });
  await LocalNotifications.registerActionTypes({
    types: [{
      id: 'TS_DAILY',
      actions: [{ id: 'OPEN', title: 'Open' }]
    }]
  });
 }
 ```
 ### 4) SQLite migration
 ```sql
 -- /migrations/00XX_notifs.sql
 CREATE TABLE IF NOT EXISTS notif_contents(
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  slot_id TEXT NOT NULL,
  payload_json TEXT NOT NULL,
  fetched_at INTEGER NOT NULL,
  etag TEXT,
  UNIQUE(slot_id, fetched_at)
 );
 CREATE INDEX IF NOT EXISTS notif_idx_contents_slot_time
  ON notif_contents(slot_id, fetched_at DESC);
 CREATE TABLE IF NOT EXISTS notif_deliveries(
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  slot_id TEXT NOT NULL,
  fire_at INTEGER NOT NULL,
  delivered_at INTEGER,
  status TEXT NOT NULL,
  error_code TEXT,
  error_message TEXT
 );
 CREATE TABLE IF NOT EXISTS notif_config(
  k TEXT PRIMARY KEY,
  v TEXT NOT NULL
 );
 ```
 *Retention job (daily):*
 ```sql
 DELETE FROM notif_contents
 WHERE fetched_at < strftime('%s','now','-14 days');
 DELETE FROM notif_deliveries
 WHERE fire_at < strftime('%s','now','-14 days');
 ```
 ### 5) Types (shared API)
 ```typescript
 // src/services/notifs/types.ts
 export type NotificationTime = { hour: number; minute: number };
 export type SlotId = string;
 export type FetchSpec = {
  method: 'GET'|'POST';
  url: string;
  headers?: Record<string,string>;
  bodyJson?: Record<string,unknown>;
  timeoutMs?: number;
 };
 export type CallbackProfile = {
  fetchContent: FetchSpec;
  ackDelivery?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  reportError?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  heartbeat?: Omit<FetchSpec,'bodyJson'> & { intervalMinutes?: number };
 };
 export type ConfigureOptions = {
  times: NotificationTime[];
  ttlSeconds?: number;
  prefetchLeadMinutes?: number;
  storage: 'shared'|'plugin';
  dbPath?: string;
  contentTemplate?: { title: string; body: string };
  callbackProfile?: CallbackProfile;
 };
 export interface DataStore {
  saveContent(slotId: SlotId, payload: unknown, etag?: string): Promise<void>;
  getLatestContent(slotId: SlotId): Promise<{
    payload: unknown;
    fetchedAt: number;
    etag?: string
  }|null>;
  recordDelivery(
    slotId: SlotId,
    fireAt: number,
    status: 'scheduled'|'shown'|'error',
    error?: { code?: string; message?: string }
  ): Promise<void>;
  enqueueEvent(e: unknown): Promise<void>;
  drainEvents(): Promise<unknown[]>;
 }
 export interface Scheduler {
  capabilities(): Promise<{ exactAlarms: boolean; maxPending?: number }>;
  scheduleExact(slotId: SlotId, whenMs: number, payloadRef: string): Promise<void>;
  scheduleWindow(
    slotId: SlotId,
    windowStartMs: number,
    windowLenMs: number,
    payloadRef: string
  ): Promise<void>;
  cancelBySlot(slotId: SlotId): Promise<void>;
  rescheduleAll(next: Array<{ slotId: SlotId; whenMs: number }>): Promise<void>;
 }
 ```
 ### 6) Adapters (thin)
 ```typescript
 // src/services/notifs/adapters/DataStoreSqlite.ts
 import type { DataStore, SlotId } from '../types';
 import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
 export class DataStoreSqlite implements DataStore {
  constructor(private platformService: PlatformServiceMixin) {}
  async saveContent(slotId: SlotId, payload: unknown, etag?: string): Promise<void> {
    const fetchedAt = Date.now();
    const payloadJson = JSON.stringify(payload);
    await this.platformService.$exec(
      `INSERT OR REPLACE INTO notif_contents (slot_id, payload_json, fetched_at, etag)
       VALUES (?, ?, ?, ?)`,
      [slotId, payloadJson, fetchedAt, etag]
    );
  }
  async getLatestContent(slotId: SlotId): Promise<{
    payload: unknown;
    fetchedAt: number;
    etag?: string
  }|null> {
    const result = await this.platformService.$db(
      `SELECT payload_json, fetched_at, etag
       FROM notif_contents
       WHERE slot_id = ?
       ORDER BY fetched_at DESC
       LIMIT 1`,
      [slotId]
    );
    if (!result || result.length === 0) {
      return null;
    }
    const row = result[0];
    return {
      payload: JSON.parse(row.payload_json),
      fetchedAt: row.fetched_at,
      etag: row.etag
    };
  }
  async recordDelivery(
    slotId: SlotId,
    fireAt: number,
    status: 'scheduled'|'shown'|'error',
    error?: { code?: string; message?: string }
  ): Promise<void> {
    const deliveredAt = status === 'shown' ? Date.now() : null;
    await this.platformService.$exec(
      `INSERT INTO notif_deliveries (slot_id, fire_at, delivered_at, status, error_code, error_message)
       VALUES (?, ?, ?, ?, ?, ?)`,
      [slotId, fireAt, deliveredAt, status, error?.code, error?.message]
    );
  }
  async enqueueEvent(e: unknown): Promise<void> {
    // Simple in-memory queue for now, can be enhanced with SQLite
    // This will be drained when app comes to foreground
  }
  async drainEvents(): Promise<unknown[]> {
    // Return and clear queued events
    return [];
  }
 }
 // src/services/notifs/adapters/SchedulerCapacitor.ts
 import { LocalNotifications } from '@capacitor/local-notifications';
 import type { Scheduler, SlotId } from '../types';
 export class SchedulerCapacitor implements Scheduler {
  async capabilities(): Promise<{ exactAlarms: boolean; maxPending?: number }> {
    // iOS: ~64 pending notifications
    // Android: depends on exact alarm permissions
    return {
      exactAlarms: true, // Assume we have permissions
      maxPending: 64
    };
  }
  async scheduleExact(slotId: SlotId, whenMs: number, payloadRef: string): Promise<void> {
    await LocalNotifications.schedule({
      notifications: [{
        id: this.generateNotificationId(slotId),
        title: 'TimeSafari',
        body: 'Your daily update is ready',
        schedule: { at: new Date(whenMs) },
        extra: { slotId, payloadRef }
      }]
    });
  }
  async scheduleWindow(
    slotId: SlotId,
    windowStartMs: number,
    windowLenMs: number,
    payloadRef: string
  ): Promise<void> {
    // For platforms that don't support exact alarms
    await LocalNotifications.schedule({
      notifications: [{
        id: this.generateNotificationId(slotId),
        title: 'TimeSafari',
        body: 'Your daily update is ready',
        schedule: {
          at: new Date(windowStartMs),
          repeats: false
        },
        extra: { slotId, payloadRef }
      }]
    });
  }
  async cancelBySlot(slotId: SlotId): Promise<void> {
    const id = this.generateNotificationId(slotId);
    await LocalNotifications.cancel({ notifications: [{ id }] });
  }
  async rescheduleAll(next: Array<{ slotId: SlotId; whenMs: number }>): Promise<void> {
    // Cancel all existing notifications
    await LocalNotifications.cancel({ notifications: [] });
    // Schedule new ones
    const notifications = next.map(({ slotId, whenMs }) => ({
      id: this.generateNotificationId(slotId),
      title: 'TimeSafari',
      body: 'Your daily update is ready',
      schedule: { at: new Date(whenMs) },
      extra: { slotId }
    }));
    await LocalNotifications.schedule({ notifications });
  }
  private generateNotificationId(slotId: SlotId): number {
    // Simple hash of slotId to generate unique notification ID
    let hash = 0;
    for (let i = 0; i < slotId.length; i++) {
      const char = slotId.charCodeAt(i);
      hash = ((hash << 5) - hash) + char;
      hash = hash & hash; // Convert to 32-bit integer
    }
    return Math.abs(hash);
  }
 }
 ```
 ### 7) Orchestrator (lean core)
 ```typescript
 // src/services/notifs/NotificationOrchestrator.ts
 import type { ConfigureOptions, SlotId, DataStore, Scheduler } from './types';
 import { logger } from '@/utils/logger';
 export class NotificationOrchestrator {
  constructor(private store: DataStore, private sched: Scheduler) {}
  private opts!: ConfigureOptions;
  async configure(o: ConfigureOptions): Promise<void> {
    this.opts = o;
    // Persist configuration to SQLite
    await this.store.enqueueEvent({
      type: 'config_updated',
      config: o,
      timestamp: Date.now()
    });
  }
  async runFullPipelineNow(): Promise<void> {
    try {
      // 1) For each upcoming slot, attempt online-first fetch
      const upcomingSlots = this.getUpcomingSlots();
      for (const slot of upcomingSlots) {
        await this.fetchAndScheduleSlot(slot);
      }
      logger.log('[NotificationOrchestrator] Full pipeline completed');
    } catch (error) {
      logger.error('[NotificationOrchestrator] Pipeline failed:', error);
      throw error;
    }
  }
  async deliverStoredNow(slotId?: SlotId): Promise<void> {
    const targetSlots = slotId ? [slotId] : this.getUpcomingSlots();
    for (const slot of targetSlots) {
      const content = await this.store.getLatestContent(slot);
      if (content) {
        const payloadRef = this.createPayloadRef(content.payload);
        await this.sched.scheduleExact(slot, Date.now() + 5000, payloadRef);
      }
    }
  }
  async reschedule(): Promise<void> {
    const nextOccurrences = this.getUpcomingSlots().map(slotId => ({
      slotId,
      whenMs: this.getNextSlotTime(slotId)
    }));
    await this.sched.rescheduleAll(nextOccurrences);
  }
  async getState(): Promise<{
    pendingCount: number;
    nextOccurrences: Array<{slotId: string; when: string}>
  }> {
    const capabilities = await this.sched.capabilities();
    const upcomingSlots = this.getUpcomingSlots();
    return {
      pendingCount: Math.min(upcomingSlots.length, capabilities.maxPending || 64),
      nextOccurrences: upcomingSlots.map(slotId => ({
        slotId,
        when: new Date(this.getNextSlotTime(slotId)).toISOString()
      }))
    };
  }
  private async fetchAndScheduleSlot(slotId: SlotId): Promise<void> {
    try {
      // Attempt online-first fetch
      if (this.opts.callbackProfile?.fetchContent) {
        const content = await this.fetchContent(slotId);
        if (content) {
          await this.store.saveContent(slotId, content.payload, content.etag);
          await this.scheduleSlot(slotId, content.payload);
          return;
        }
      }
      // Fallback to offline-first
      const storedContent = await this.store.getLatestContent(slotId);
      if (storedContent && this.isWithinTTL(storedContent.fetchedAt)) {
        await this.scheduleSlot(slotId, storedContent.payload);
      }
    } catch (error) {
      logger.error(`[NotificationOrchestrator] Failed to fetch/schedule ${slotId}:`, error);
      await this.store.recordDelivery(slotId, Date.now(), 'error', {
        code: 'fetch_failed',
        message: error instanceof Error ? error.message : 'Unknown error'
      });
    }
  }
  private async fetchContent(slotId: SlotId): Promise<{
    payload: unknown;
    etag?: string
  }|null> {
    const spec = this.opts.callbackProfile!.fetchContent;
    const response = await fetch(spec.url, {
      method: spec.method,
      headers: spec.headers,
      body: spec.bodyJson ? JSON.stringify(spec.bodyJson) : undefined,
      signal: AbortSignal.timeout(spec.timeoutMs || 15000)
    });
    if (response.status === 304) {
      return null; // Not modified
    }
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    const payload = await response.json();
    const etag = response.headers.get('etag') || undefined;
    return { payload, etag };
  }
  private async scheduleSlot(slotId: SlotId, payload: unknown): Promise<void> {
    const whenMs = this.getNextSlotTime(slotId);
    const payloadRef = this.createPayloadRef(payload);
    await this.sched.scheduleExact(slotId, whenMs, payloadRef);
    await this.store.recordDelivery(slotId, whenMs, 'scheduled');
  }
  private getUpcomingSlots(): SlotId[] {
    const now = new Date();
    const slots: SlotId[] = [];
    for (const time of this.opts.times) {
      const slotId = `slot-${time.hour.toString().padStart(2, '0')}-${time.minute.toString().padStart(2, '0')}`;
      const nextTime = this.getNextSlotTime(slotId);
      // Include slots for today and tomorrow (within rolling window)
      if (nextTime <= now.getTime() + (2 * 24 * 60 * 60 * 1000)) {
        slots.push(slotId);
      }
    }
    return slots;
  }
  private getNextSlotTime(slotId: SlotId): number {
    const [_, hourStr, minuteStr] = slotId.match(/slot-(\d{2})-(\d{2})/) || [];
    const hour = parseInt(hourStr, 10);
    const minute = parseInt(minuteStr, 10);
    const now = new Date();
    const next = new Date(now);
    next.setHours(hour, minute, 0, 0);
    // If time has passed today, schedule for tomorrow
    if (next <= now) {
      next.setDate(next.getDate() + 1);
    }
    return next.getTime();
  }
  private createPayloadRef(payload: unknown): string {
    return `payload-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
  }
  private isWithinTTL(fetchedAt: number): boolean {
    const ttlMs = (this.opts.ttlSeconds || 86400) * 1000;
    return Date.now() - fetchedAt < ttlMs;
  }
 }
 ```
 ### 8) Bootstrap + feature flags
 ```typescript
 // /app/bootstrap/notifications.ts
 import { initNotifChannels } from './initNotifChannels';
 import { NotificationOrchestrator } from '@/services/notifs/NotificationOrchestrator';
 import { DataStoreSqlite } from '@/services/notifs/adapters/DataStoreSqlite';
 import { SchedulerCapacitor } from '@/services/notifs/adapters/SchedulerCapacitor';
 import { PlatformServiceMixin } from '@/utils/PlatformServiceMixin';
 import { Capacitor } from '@capacitor/core';
 let orchestrator: NotificationOrchestrator | null = null;
 export async function initNotifications(): Promise<void> {
  // Only initialize on Capacitor platforms
  if (!Capacitor.isNativePlatform()) {
    return;
  }
  try {
    await initNotifChannels();
    const platformService = new PlatformServiceMixin();
    const store = new DataStoreSqlite(platformService);
    const scheduler = new SchedulerCapacitor();
    orchestrator = new NotificationOrchestrator(store, scheduler);
    // Run pipeline on app start
    await orchestrator.runFullPipelineNow();
    await orchestrator.reschedule();
    logger.log('[Notifications] Initialized successfully');
  } catch (error) {
    logger.error('[Notifications] Initialization failed:', error);
  }
 }
 export function getNotificationOrchestrator(): NotificationOrchestrator | null {
  return orchestrator;
 }
 ```
 ### 9) Service Worker click handler (web)
 ```javascript
 // sw_scripts/notification-click.js (or inside combined file)
 self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  // Extract slotId from notification data
  const slotId = event.notification.data?.slotId;
  // Open appropriate route based on notification type
  const route = slotId ? '/#/daily' : '/#/notifications';
  event.waitUntil(
    clients.openWindow(route).catch(() => {
      // Fallback if openWindow fails
      return clients.openWindow('/');
    })
  );
 });
 ```
 ---
 ## Acceptance (v1)
 - Local notifications **fire at configured slots with the app killed** (iOS/Android)
 - **Online-first** → 304/ETag respected; **offline-first** fallback; **TTL** policy respected
 - **14-day retention** job prunes contents & deliveries
 - **TZ/DST** change triggers **reschedule()**; rolling window adheres to iOS pending cap
 - **Feature flags** present: `scheduler: 'capacitor'|'native'`, `mode: 'online-first'|'offline-first'|'auto'`
 ---
 ## Platform Notes
 - **Capacitor Only**: This implementation is designed for iOS/Android via Capacitor
 - **Web Fallback**: Web platform will use existing service worker + push notifications
 - **Electron**: Will need separate implementation using native notification APIs
 - **Feature Flags**: Can be toggled per platform in bootstrap configuration
 - **Android UX**: Settings deep-link to grant exact-alarm special access on API 31+
 - **DST/TZ Guardrail**: On app resume, if offset/TZ changed → `reschedule()` and re-arm today's slots
--- a/doc/notification-system-implementation.md
+++ b/doc/notification-system-implementation.md
--- a/doc/notification-system-plan.md
+++ b/doc/notification-system-plan.md
@ -0,0 +1,457 @@
 # TimeSafari Notification System — Strategic Plan
 **Status:** 🚀 Active plan  
 **Date:** 2025-09-05T05:09Z (UTC)  
 **Author:** Matthew Raymer  
 **Scope:** v1 (in‑app orchestrator) now; path to v2 (native plugin) next  
 **Goal:** We **will deliver** 1..M local notifications/day with content **prefetched** so messages **will display offline**. We **will support** online‑first (API→DB→Schedule) with offline‑first fallback. The system **will enhance** TimeSafari's community-building mission by keeping users connected to gratitude, gifts, and collaborative projects through timely, relevant notifications.
 > **Implementation Details:** See `notification-system-implementation.md` for detailed code, database schemas, and integration specifics.  
 > **Canonical Ownership:** This document owns Goals, Tenets, Platform behaviors, Acceptance criteria, and Test cases.
 ---
 ## 1) Versioning & Intent
 - **v1 (In‑App Orchestrator):** We **will implement** multi‑daily local notifications, online/offline flows, templating, SQLite persistence, and eventing **inside the app** using Capacitor Local Notifications.  
 - **v2 (Plugin):** We **will extract** adapters to a Capacitor/Native plugin to gain native schedulers (WorkManager/AlarmManager; BGTask+UNUserNotificationCenter), native HTTP, and native SQLite **with the same TypeScript API**.
 > We **will retain** the existing web push + Service Worker foundation; the system **will add** reliable local scheduling on mobile and a unified API across platforms.
 ---
 ## 2) Design Tenets
 - **Reliability:** OS‑level delivery once scheduled; no reliance on JS being alive at fire time.  
 - **Freshness:** Prefer online‑first within a short prefetch window; degrade gracefully to cached content with TTL.  
 - **Extractable:** Clean interfaces (Scheduler, DataStore, Callbacks) so v2 **will swap** adapters without API changes.  
 - **Simplicity:** One‑shot notifications per slot; rolling window scheduling to respect platform caps.  
 - **Observability:** Persist deliveries and errors; surface minimal metrics; enable ACKs.
 - **Privacy-First:** Follow TimeSafari's privacy-preserving architecture; user-controlled visibility and data sovereignty.
 - **Community-Focused:** Enhance TimeSafari's mission of connecting people through gratitude, gifts, and collaborative projects.
 ---
 ## 3) Architecture Overview
 ```
 Application (Vue/TS)
 ├─ NotificationOrchestrator (core state)
 │   ├─ Scheduler (adapter)
 │   ├─ DataStore (adapter)
 │   └─ Callbacks (adapter)
 └─ UI (settings, status)
 Adapters
 ├─ V1: SchedulerCapacitor, DataStoreSqlite, CallbacksHttp
 └─ V2: SchedulerNative, DataStoreNativeSqlite, CallbacksNativeHttp
 Platform
 ├─ iOS/Android: LocalNotifications (+ native bridges later)
 ├─ Web: Service Worker + Push (kept)
 └─ Electron: OS notifications (thin adapter)
 ```
 **Execution modes (concise):**  
 - **Online‑First:** wake near slot → fetch (ETag, timeout) → persist → schedule; on failure → Offline‑First.  
 - **Offline‑First:** read last good payload from SQLite; if beyond TTL → skip notification (no retry).
 ---
 ## 4) Public API (Shared by v1 & v2)
 ```ts
 export type NotificationTime = { hour: number; minute: number }; // local wall-clock
 export type SlotId = string; // Format: "HHmm" (e.g., "0800", "1200", "1800") - stable across TZ changes
 export type FetchSpec = {
  method: 'GET'|'POST';
  url: string;
  headers?: Record<string,string>;
  bodyJson?: Record<string,unknown>;
  timeoutMs?: number;
 };
 export type CallbackProfile = {
  fetchContent: FetchSpec;
  ackDelivery?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  reportError?: Omit<FetchSpec,'bodyJson'|'timeoutMs'>;
  heartbeat?: Omit<FetchSpec,'bodyJson'> & { intervalMinutes?: number };
 };
 export type ConfigureOptions = {
  times: NotificationTime[];                  // 1..M daily
  timezone?: string;                          // Default: system timezone
  ttlSeconds?: number;                        // Default: 86400 (24h)
  prefetchLeadMinutes?: number;               // Default: 20
  storage: 'shared'|'private';               // Required
  contentTemplate: { title: string; body: string }; // Required
  callbackProfile?: CallbackProfile;          // Optional
 };
 export interface MultiDailyNotification {
  requestPermissions(): Promise<void>;
  configure(o: ConfigureOptions): Promise<void>;
  runFullPipelineNow(): Promise<void>;        // API→DB→Schedule (today's remaining)
  deliverStoredNow(slotId?: SlotId): Promise<void>; // 60s cooldown guard
  reschedule(): Promise<void>;
  getState(): Promise<{
    nextOccurrences: Array<{ slotId: SlotId; when: string }>; // ISO
    lastFetchAt?: string; lastDeliveryAt?: string;
    pendingCount: number; exactAlarmCapable?: boolean;
  }>;
 }
 ```
 > **Storage semantics:** `'shared'` = app DB; `'private'` = plugin-owned/native DB (v2). (No functional difference in v1.)
 > **Slot Identity & Scheduling Policy**
 > • **SlotId** uses canonical `HHmm` and remains stable across timezone changes.
 > • **Lead window:** default `prefetchLeadMinutes = 20`; no retries once inside the lead.
 > • **TTL policy:** When offline and content is beyond TTL, **we will skip** the notification (no "(cached)" suffix).
 > • **Idempotency:** Duplicate "scheduled" deliveries are prevented by a unique index on `(slot_id, fire_at, status='scheduled')`.
 > • **Time handling:** Slots will follow **local wall-clock** time across TZ/DST; `slotId=HHmm` stays constant and we will **recompute fire times** on offset change.
 ---
 ## 5) Data Model & Retention (SQLite)
 **Tables:** `notif_contents`, `notif_deliveries`, `notif_config`
 **Retention:** We **will keep** ~14 days of contents/deliveries (configurable) and **will prune** via a simple daily job that runs on app start/resume. We **will prune** daily but **will not** VACUUM by default on mobile; disk compaction is deferred.
 **Payload handling:** We **will template** `{title, body}` **before** scheduling; we **will not** mutate at delivery time.
 ---
 ## 6) Scheduling Policy & Slot Math
 - **One‑shot per slot** per day (non‑repeating).  
 - **Rolling window:** today's remaining slots; seed tomorrow where platform limits allow. v1 will schedule **the next occurrence per slot** by default; a **configurable depth** (0=today, 1=today+tomorrow) may be enabled as long as the iOS pending cap is respected.
 - **TZ/DST safe:** We **will recompute** local wall‑times on app resume and whenever timezone/offset changes; then **reschedule**.  
 - **Android exactness:** If exact alarms are unavailable or denied, we **will use** `setWindow` semantics via the scheduler adapter.  
 - **iOS pending cap:** We **will keep** pending locals within typical caps (~64) by limiting the window and canceling/re‑arming as needed.
 - **Electron rolling window:** On Electron we **will schedule** the **next occurrence per slot** by default; depth (today+tomorrow) **will be** enabled only when auto-launch is on, to avoid drift while the app is closed.
 ---
 ## 7) Platform Essentials
 **iOS**  
 - Local notifications **will** fire without background runtime once scheduled. NSE **will not** mutate locals; delivery-time enrichment requires remote push (future).
 - **Category ID**: `TS_DAILY` with default `OPEN` action
 - **Background budget** is short and OS‑managed; any prefetch work **will complete** promptly.
 - **Mobile local notifications will route via action listeners (not the service worker)**.
 **Android**  
 - Exact alarms on **API 31+** may require `SCHEDULE_EXACT_ALARM`. If exact access is missing on API 31+, we will use a **windowed trigger (default ±10m)** and surface a settings deep-link.
 - **We will deep-link users to the exact-alarm settings when we detect denials.**
 - **Channel defaults**: ID `timesafari.daily`, name "TimeSafari Daily", importance=high (IDs never change)
 - Receivers for reboot/time change **will be handled** by v2 (plugin); in v1, re‑arming **will occur** on app start/resume.
 - **Mobile local notifications will route via action listeners (not the service worker)**.
 **Web**  
 - Requires registered Service Worker + permission; can deliver with browser closed. **Web will not offline-schedule**.
 - Service worker click handlers apply to **web push only**; local notifications on mobile do **not** pass through the SW.
 - SW examples use `/sw.js` as a placeholder; **wire this to your actual build output path** (e.g., `sw_scripts/notification-click.js` or your combined bundle).
 - **Note**: Service workers are **intentionally disabled** in Electron (`src/main.electron.ts`) and web uses VitePWA plugin for minimal implementation.
 **Electron**  
 - We **will use** native OS notifications with **best-effort scheduling while the app is running**; true background scheduling will be addressed in v2 (native bridges).
 **Electron delivery strategy (v1 reality + v2 path)**  
 We **will deliver** desktop notifications while the Electron app is running. True **background scheduling when the app is closed** is **out of scope for v1** and **will be addressed** in v2 via native bridges. We **will adopt** one of the following options (in order of fit to our codebase):
 **In-app scheduler + auto-launch (recommended now):** Keep the orchestrator in the main process, **start on login** (tray app, hidden window), and use the **Electron `Notification` API** for delivery. This requires no new OS services and aligns with our PlatformServiceFactory/mixin patterns.
 **Policy (v1):** If the app is **not running**, Electron will **not** deliver scheduled locals. With **auto-launch enabled**, we **will achieve** near-mobile parity while respecting OS sleep/idle behavior.
 **UX notes:** On Windows we **will set** `appUserModelId` so toasts are attributed correctly; on macOS we **will request** notification permission on first use.
 **Prerequisites:** We **will require** Node 18+ (global `fetch`) or we **will polyfill** via `undici` for content fetching in the main process.
 ---
 ## 8) Template Engine Contract
 **Supported tokens:** `{{headline}}`, `{{summary}}`, `{{date}}` (YYYY-MM-DD), `{{time}}` (HH:MM).  
 **Escaping:** HTML-escape all injected values.  
 **Limits:** Title ≤ 50 chars; Body ≤ 200 chars; truncate with ellipsis.  
 **Fallback:** Missing token → `"[Content]"`.  
 **Mutation:** We **will** render templates **before** scheduling; no mutation at delivery time on iOS locals.
 ## 9) Integration with Existing TimeSafari Infrastructure
 **Database:** We **will integrate** with existing migration system in `src/db-sql/migration.ts` following the established `MIGRATIONS` array pattern  
 **Settings:** We **will extend** existing Settings type in `src/db/tables/settings.ts` following the established type extension pattern  
 **Platform Service:** We **will leverage** existing PlatformServiceMixin database utilities following the established mixin pattern  
 **Service Factory:** We **will follow** the existing `PlatformServiceFactory` singleton pattern for notification service creation  
 **Capacitor:** We **will integrate** with existing deep link system in `src/main.capacitor.ts` following the established initialization pattern  
 **Service Worker:** We **will extend** existing service worker infrastructure following the established `sw_scripts/` pattern (Note: Service workers are intentionally disabled in Electron and have minimal web implementation via VitePWA plugin)  
 **API:** We **will use** existing error handling from `src/services/api.ts` following the established `handleApiError` pattern  
 **Logging:** We **will use** existing logger from `src/utils/logger` following the established logging patterns  
 **Platform Detection:** We **will use** existing `process.env.VITE_PLATFORM` patterns (`web`, `capacitor`, `electron`)  
 **Vue Architecture:** We **will follow** Vue 3 + vue-facing-decorator patterns for component integration (Note: The existing `useNotifications` composable in `src/composables/useNotifications.ts` is currently stub functions with eslint-disable comments and needs implementation)  
 **State Management:** We **will integrate** with existing settings system via `PlatformServiceMixin.$saveSettings()` for notification preferences (Note: TimeSafari uses PlatformServiceMixin for all state management, not Pinia stores)  
 **Identity System:** We **will integrate** with existing `did:ethr:` (Ethereum-based DID) system for user context  
 **Testing:** We **will follow** Playwright E2E testing patterns established in TimeSafari  
 **Database Architecture:** We **will support** platform-specific database backends:
 - **Web**: Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
 - **Capacitor**: Native SQLite via `CapacitorPlatformService` 
 - **Electron**: Native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)  
 ---
 ## 10) Error Taxonomy & Telemetry
 **Error Codes:** `FETCH_TIMEOUT`, `ETAG_NOT_MODIFIED`, `SCHEDULE_DENIED`, `EXACT_ALARM_MISSING`, `STORAGE_BUSY`, `TEMPLATE_MISSING_TOKEN`, `PERMISSION_DENIED`.
 **Event Envelope:** `code, slotId, whenMs, attempt, networkState, tzOffset, appState, timestamp`.
 ---
 ## 11) Permission UX & Channels/Categories
 - We **will request** notification permission **after** user intent (e.g., settings screen), not on first render.  
 - **Android:** We **will create** a stable channel ID (e.g., `timesafari.daily`) and **will set** importance appropriately.  
 - **iOS:** We **will register** categories for optional actions; grouping may use `threadIdentifier` per slot/day.
 ---
 ## 12) Eventing & Telemetry
 ### Error Taxonomy
 **Finite error code set:**
 - `FETCH_TIMEOUT` - Network request exceeded timeout
 - `ETAG_NOT_MODIFIED` - Server returned 304 (expected)
 - `SCHEDULE_DENIED` - OS denied notification scheduling
 - `EXACT_ALARM_MISSING` - Android exact alarm permission absent
 - `STORAGE_BUSY` - Database locked or unavailable
 - `TEMPLATE_MISSING_TOKEN` - Required template variable not found
 - `PERMISSION_DENIED` - User denied notification permissions
 ### Event Logging Envelope
 ```ts
 {
  code: string,           // Error code from taxonomy
  slotId: string,         // Affected slot
  whenMs: number,         // Scheduled time
  attempt: number,        // Retry attempt (1-based)
  networkState: string,   // 'online' | 'offline'
  tzOffset: number,       // Current timezone offset
  appState: string,       // 'foreground' | 'background' | 'killed'
  timestamp: number       // UTC timestamp
 }
 ```
 ### ACK Payload Format
 ```ts
 {
  slotId: string,
  fireAt: number,         // Scheduled time
  deliveredAt: number,    // Actual delivery time
  deviceTz: string,       // Device timezone
  appVersion: string,     // App version
  buildId: string         // Build identifier
 }
 ```
 - **Event queue (v1):** In-memory queue for `delivery`, `error`, `heartbeat` events. Background/native work **will enqueue**; foreground **will drain** and publish to the UI. **v2 will migrate** to SQLite-backed queue for persistence.  
 - **Callbacks (optional):** `ackDelivery`, `reportError`, `heartbeat` **will post** to server endpoints when configured.  
 - **Minimal metrics:** pending count, last fetch, last delivery, next occurrences.
 ---
 ## 13) Feature Flags & Config
 ### Feature Flags Table
 | Flag | Default | Description | Location |
 |------|---------|-------------|----------|
 | `scheduler` | `'capacitor'` | Scheduler implementation | `notif_config` table |
 | `mode` | `'auto'` | Online-first inside lead, else offline-first | `notif_config` table |
 | `prefetchLeadMinutes` | `20` | Lead time for prefetch attempts | `notif_config` table |
 | `ttlSeconds` | `86400` | Content staleness threshold (24h) | `notif_config` table |
 | `iosCategoryIdentifier` | `'TS_DAILY'` | iOS notification category | `notif_config` table |
 | `androidChannelId` | `'timesafari.daily'` | Android channel ID (never changes) | `notif_config` table |
 **Storage:** Feature flags **will reside** in `notif_config` table as key-value pairs, separate from user settings.
 ---
 ## 14) Acceptance (Definition of Done) → Test Cases
 ### Explicit Test Checks
 - **App killed → locals fire**: Configure slots at 8:00, 12:00, 18:00; kill app; verify notifications fire at each slot on iOS/Android
 - **ETag 304 path**: Server returns 304 → keep previous content; locals fire with cached payload
 - **ETag 200 path**: Server returns 200 → update content and re-arm locals with fresh payload
 - **Offline + beyond TTL**: When offline and content > 24h old → skip notification (no "(cached)" suffix)
 - **iOS pending cap**: Respect ~64 pending limit; cancel/re-arm as needed within rolling window
 - **Exact-alarm denied**: Android permission absent → windowed schedule (±10m) activates; UI shows fallback hint
 - **Permissions disabled** → we will record `SCHEDULE_DENIED` and refrain from queuing locals.
 - **Window fallback** → when exact alarm is absent on Android, verify target fires within **±10m** of slot time (document as an E2E expectation).
 - **Timezone change**: On TZ/DST change → recompute wall-clock times; cancel & re-arm all slots
 - **Lead window respect**: No retries attempted once inside 20min lead window
 - **Idempotency**: Multiple `runFullPipelineNow()` calls don't create duplicate scheduled deliveries
 - **Cooldown guard**: `deliverStoredNow()` has 60s cooldown to prevent double-firing
 ### Electron-Specific Test Checks
 - **Electron running (tray or window) → notifications fire** at configured slots using Electron `Notification`
 - **Electron not running →** no delivery (documented limitation for v1)
 - **Start on Login enabled →** after reboot + login, orchestrator **will re-arm** slots and deliver
 - **Template limits honored** (Title ≤ 50, Body ≤ 200) on Electron notifications
 - **SW scope** not used for Electron (click handlers are **web only**)
 - **Windows appUserModelId** set correctly for toast attribution
 - **macOS notification permission** requested on first use
 ---
 ## 15) Test Matrix (Essentials)
 - **Android:** exact vs inexact branch, Doze/App Standby behavior, reboot/time change, permission denial path, deep‑link to exact‑alarm settings.  
 - **iOS:** BG fetch budget limits, pending cap windowing, local notification delivery with app terminated, category actions.  
 - **Web:** SW lifecycle, push delivery with app closed, click handling, no offline scheduling.  
 - **Cross‑cutting:** ETag/304 behavior, TTL policy, templating correctness, event queue drain, SQLite retention job.
 ---
 ## 16) Migration & Rollout Notes
 - We **will keep** existing web push flows intact.  
 - We **will introduce** the orchestrator behind a feature flag, initially with a small number of slots.  
 - We **will migrate** settings to accept multiple times per day.  
 - We **will document** platform caveats inside user‑visible settings (e.g., Android exact alarms, iOS cap).
 ---
 ## 17) Security & Privacy
 - Tokens **will reside** in Keystore/Keychain (mobile) and **will be injected** at request time; they **will not** be stored in SQLite.  
 - Optionally, SQLCipher at rest for mobile; redaction of PII in logs; payload size caps.  
 - Content **will be** minimal (title/body); sensitive data **will not be** embedded.
 ---
 ## 18) Non‑Goals (Now)
 - Complex action sets and rich media on locals (kept minimal).  
 - Delivery‑time mutation of local notifications on iOS (NSE is for remote).  
 - Full analytics pipeline (future enhancement).
 ---
 ## 19) Cross-Doc Sync Hygiene
 ### Canonical Ownership
 - **This document (Plan)**: Canonical for Goals, Tenets, Platform behaviors, Acceptance criteria, Test cases
 - **Implementation document**: Canonical for API definitions, Database schemas, Adapter implementations, Code examples
 ### PR Checklist
 When changing notification system behavior, update both documents:
 - [ ] **API changes**: Update types/interfaces in both Plan §4 and Implementation §3
 - [ ] **Schema changes**: Update Plan §5 and Implementation §2  
 - [ ] **Slot/TTL changes**: Update Plan §4 semantics and Implementation §6 logic
 - [ ] **Template changes**: Update Plan §9 contract and Implementation examples
 - [ ] **Error codes**: Update Plan §11 taxonomy and Implementation error handling
 ### Synchronization Points
 - **API code blocks**: Must be identical between Plan §4 and Implementation §3 (Public API (Shared))
 - **Feature flags**: Must match between Plan §12 table and Implementation defaults
 - **Test cases**: Plan §13 acceptance criteria must align with Implementation test examples
 - **Slot/TTL/Lead policies**: Must be identical between Plan §4 policy and Implementation §3 policy
 ---
 ## 21) Privacy & Security Alignment
 ### Privacy-First Architecture
 - **User-Controlled Visibility:** Notification preferences **will be** user-controlled with explicit opt-in/opt-out
 - **Data Sovereignty:** All notification data **will reside** on user's device; no external tracking or analytics
 - **Minimal Data Collection:** We **will collect** only essential data for notification delivery (slot times, content templates)
 - **DID Integration:** Notifications **will be** associated with user's Decentralized Identifier (DID) for privacy-preserving identity
 ### Security Considerations
 - **Content Encryption:** Sensitive notification content **will be** encrypted at rest using device keystore
 - **Secure Transmission:** All API calls **will use** HTTPS with proper certificate validation
 - **Input Validation:** All notification content **will be** validated and sanitized before storage
 - **Access Control:** Notification settings **will be** protected by user authentication
 ### Compliance with TimeSafari Principles
 - **Privacy-Preserving:** Follows TimeSafari's privacy-preserving claims architecture
 - **User Agency:** Users maintain full control over their notification experience
 - **Transparency:** Clear communication about what data is collected and how it's used
 - **Minimal Footprint:** Notification system **will have** minimal impact on user privacy
 ---
 ## 23) Platform-Specific Implementation Details
 ### Web Platform (`VITE_PLATFORM=web`)
 - **Database:** Uses Absurd SQL (SQLite via IndexedDB) via `WebPlatformService` with worker pattern
 - **Notifications:** Web push notifications via Service Worker (minimal implementation)
 - **Local Scheduling:** **Not supported** - web cannot schedule local notifications offline
 - **API Integration:** Direct HTTP calls for content fetching
 - **Storage:** Notification preferences stored in Absurd SQL database
 - **Testing:** Playwright E2E tests run on web platform
 ### Capacitor Platform (`VITE_PLATFORM=capacitor`)
 - **Database:** Uses native SQLite via `CapacitorPlatformService`
 - **Notifications:** Local notifications via `@capacitor/local-notifications`
 - **Local Scheduling:** **Fully supported** - OS-level notification scheduling
 - **API Integration:** HTTP calls with mobile-optimized timeouts and retry logic
 - **Storage:** Notification preferences stored in native SQLite database
 - **Testing:** Playwright E2E tests run on mobile devices (Android/iOS)
 ### Electron Platform (`VITE_PLATFORM=electron`)
 - **Database:** Uses native SQLite via `ElectronPlatformService` (extends CapacitorPlatformService)
 - **Notifications:** OS-level notifications via Electron's notification API
 - **Local Scheduling:** **Supported** - desktop OS notification scheduling
 - **API Integration:** Same as Capacitor platform
 - **Storage:** Same as Capacitor platform (via inherited service)
 - **Testing:** Same as Capacitor platform
 ### Cross-Platform Considerations
 - **Feature Detection:** Use `process.env.VITE_PLATFORM` for platform-specific behavior
 - **Database Abstraction:** PlatformServiceMixin handles database differences transparently
 - **API Consistency:** Same TypeScript API across all platforms
 - **Fallback Behavior:** Web platform gracefully degrades to push-only notifications
 ---
 ## 24) TimeSafari Architecture Compliance
 ### Design Pattern Adherence
 - **Factory Pattern:** Notification service follows `PlatformServiceFactory` singleton pattern
 - **Mixin Pattern:** Database access uses existing `PlatformServiceMixin` pattern
 - **Migration Pattern:** Database changes follow existing `MIGRATIONS` array pattern
 - **Error Handling:** Uses existing `handleApiError` from `src/services/api.ts`
 - **Logging:** Uses existing logger from `src/utils/logger` with established patterns
 - **Platform Detection:** Uses existing `Capacitor.isNativePlatform()` and `VITE_PLATFORM` patterns
 ### File Organization Compliance
 - **Services:** Follows existing `src/services/` organization with factory and adapters
 - **Database:** Extends existing `src/db-sql/migration.ts` and `src/db/tables/settings.ts`
 - **Utils:** Extends existing `src/utils/PlatformServiceMixin.ts`
 - **Main Entry:** Integrates with existing `src/main.capacitor.ts` initialization
 - **Service Workers:** Follows existing `sw_scripts/` organization
 ### Type Safety Compliance
 - **Settings Extension:** Follows existing Settings type extension pattern
 - **Interface Definitions:** Uses existing TypeScript interface patterns
 - **Error Types:** Follows existing error handling type patterns
 - **Platform Types:** Uses existing platform detection type patterns
 ---
 ## Sync Checklist
 | Sync item                      | Plan                  | Impl                  | Status    |
 | ------------------------------ | --------------------- | --------------------- | --------- |
 | Public API block identical     | §4                    | §3                    | ✅         |
 | `getState()` fields present    | §4                    | §8 Orchestrator       | ✅         |
 | Capacitor action handlers      | §7 (iOS/Android note) | §9 Bootstrap          | ✅         |
 | Electron fetch prereq/polyfill | §7                    | §9 Electron           | ✅         |
 | Android ±10m fallback          | §7                    | §7 SchedulerCapacitor | ✅         |
 | Retention (no VACUUM v1)       | §5                    | `$pruneNotifData`     | ✅         |
 ---
 *This strategic plan focuses on features and future‑tense deliverables, avoids implementation details, and preserves a clear path from the in‑app implementation (v1) to the native plugin (v2). For detailed implementation specifics, see `notification-system-implementation.md`.*