Implement Insulin Dose and Glucose Reading Warning (KD-95)

docs/warning-system-architecture.md

@@ -0,0 +1,164 @@
+# Warning System Architecture Documentation
+
+## 1. System Overview and Safety-Critical Nature
+
+The Warning System is a core safety-critical component designed to proactively identify and communicate potential hazards related to insulin dosing and glucose monitoring. It aims to minimize patient risk by delivering timely alerts and preventing adverse events through intelligent warning orchestration.
+
+This system operates in a real-time, healthcare-regulated environment where accuracy, reliability, and promptness of warnings are paramount. It supports clinical decision-making by interpreting physiological data streams, detecting anomalies, and managing alert delivery with stringent safety controls.
+
+---
+
+## 2. Insulin Dose Warning Logic and Thresholds
+
+### Logic
+
+- Warnings are triggered when insulin doses approach or exceed predefined clinical safety thresholds.
+- Dose escalation beyond a patient-specific maximum cumulative dose initiates immediate alerting.
+- Rate-of-change monitoring detects abrupt increases in dosing patterns to flag potential overdosing.
+- Thresholds incorporate both absolute and relative measures customized per patient profile.
+
+### Thresholds
+
+| Parameter                          | Threshold Value                  |
+|----------------------------------|--------------------------------|
+| Maximum single insulin dose       | Patient-specific upper limit   |
+| Maximum cumulative 24-hour dose   | Patient-specific limit          |
+| Dose escalation rate              | >20% increase over prior dose  |
+| Minimum safe interval between doses | 90 minutes                   |
+
+When a threshold breach occurs, the system generates a tiered warning classified by severity and urgency.
+
+---
+
+## 3. Glucose Reading Staleness Detection
+
+- Glucose readings are considered stale if no new data arrive within a configurable timeout window (default: 10 minutes).
+- Staleness detection evaluates sensor data recency and flags loss-of-signal or offline status.
+- Warnings are generated to alert users and supervising clinicians of potential data reliability issues.
+- This ensures the warning system acts only on fresh, valid data, preserving patient safety.
+
+---
+
+## 4. Warning Orchestration and Prioritization
+
+- Multi-source warnings (insulin dose, glucose staleness, anomaly alerts) are prioritized using a risk-based hierarchy.
+- Severity levels: Critical > High > Medium > Low
+- Concurrent warnings are aggregated and presented in order of clinical urgency.
+- Suppression and escalation logic prevent alert fatigue while ensuring critical warnings are always delivered.
+- Contextual patient state and historical warnings influence warning escalation rules.
+
+---
+
+## 5. Notification Delivery Architecture
+
+- Warning delivery utilizes a robust, event-driven architecture.
+- Notifications propagate through multi-channel pathways:
+  - On-device visual/auditory alerts
+  - SMS and email for caregiver escalation
+  - Integration with EHR systems via secure HL7/FHIR endpoints
+- Delivery acknowledgement and retry mechanisms ensure notification integrity.
+- End-to-end encryption, authentication, and audit logging maintain compliance and patient confidentiality.
+
+---
+
+## 6. Risk Controls
+
+### Patient Access Controls (Ref: KXREC0XP3JDJKEA9YRVHNVAMF70YJJ1)
+
+- Role-based authentication strictly limits patient access to warning management interfaces.
+- Read-only views are enforced for patient users.
+- Sensitive controls and configuration are restricted to clinical staff and administrators.
+- Access attempts are logged and audited with anomaly detection.
+
+### System Downtime Management (Ref: KXREC74BEX3AQ999FRA2V4DVJ6D17BK)
+
+- Redundant failover infrastructure ensures high availability.
+- Heartbeat monitoring detects downtime within seconds.
+- Safe fallback procedures maintain minimum warning capabilities during partial outages.
+- Downtime events trigger automated escalation protocols.
+
+### Slow Response Handling (Ref: KXREC470MGTR35J8NVRS1GYDMEKMMGH)
+
+- Performance thresholds initiate warnings if warning generation or delivery latency exceeds acceptable bounds.
+- Load balancing and resource scaling mitigate slowdowns caused by traffic spikes.
+- System health dashboards enable proactive capacity management.
+
+### Alert Failure Detection and Handling (Ref: KXREC5NAWF8QGET8M595JZCG30PDG1B)
+
+- Monitoring systems detect failed or undelivered alerts.
+- Automatic retries and alternate notification channels reduce failure impact.
+- Critical failure events raise incident tickets and notify technical responders immediately.
+
+---
+
+## 7. Predictive Model Reliability and Anomaly Detection Sensitivity
+
+### Predictive Model Reliability (Ref: KXREC5HB8JW72E99MFSDJAD4SKH6YQN)
+
+- Models trained on diverse datasets ensure consistent predictive accuracy.
+- Continuous model validation monitors precision/recall metrics.
+- Retraining is triggered when performance degrades below defined thresholds.
+- Model explainability features assist clinical verification of warnings.
+
+### Anomaly Detection Sensitivity (Ref: KXREC50ZS9YFJP789V9G2FPYTMT1KJK)
+
+- Sensitivity thresholds are calibrated to balance false positives/negatives.
+- Adaptive learning adjusts to patient-specific baselines over time.
+- Alert tuning interfaces allow clinicians to customize sensitivity per patient risk profile.
+
+---
+
+## 8. Integration with Visualization Interface Parent Component (Ref: KXREC5Y1CC4NYQ28M1VNYPAC35SD85Z)
+
+- The Warning System exposes a standardized API for real-time warning data retrieval.
+- Integration supports seamless embedding of alert status within the parent visualization interface.
+- Supports event subscriptions, filterable warning streams, and acknowledgement feedback.
+- UI design promotes clear, unambiguous presentation of warning states.
+
+---
+
+## 9. Performance Requirements and Monitoring
+
+- Latency from detection to notification: < 2 seconds
+- System uptime: 99.9% operational over rolling 30-day periods
+- Throughput: Supports simultaneous monitoring of up to 10,000 patients
+- Continuous health monitoring includes:
+  - Latency and error rate logging
+  - Resource usage statistics
+  - User activity and notification metrics
+- Alerts raised for SLA violations trigger automated remediation workflows.
+
+---
+
+## 10. Testing Strategy
+
+- **Functional Testing:** Validates warning logic against defined insulin dose and glucose staleness scenarios.
+- **Integration Testing:** Confirms proper notification delivery and interface embedding.
+- **Safety and Failover Testing:** Exercises failure modes including downtime, slow response, and alert failures.
+
+Three primary test protocols:
+
+1. **Dose Threshold Breach Simulation:** Verifies warning generation under boundary conditions.
+2. **Data Staleness and Anomaly Injection:** Ensures staleness detection and anomaly warnings trigger correctly.
+3. **System Failures and Recovery:** Assesses reliability mechanisms and escalation during partial outages.
+
+Test coverage includes automated unit tests, manual clinical scenario evaluations, and load testing.
+
+---
+
+## 11. Failure Modes and Mitigation
+
+| Failure Mode                    | Impact                                | Mitigation Strategy                               |
+|--------------------------------|-------------------------------------|--------------------------------------------------|
+| Sensor Data Unavailability      | Missed or delayed warnings           | Staleness detection, fallback alerting            |
+| Predictive Model Degradation    | Inaccurate warnings                  | Continuous validation, automatic retraining      |
+| Notification Delivery Failures  | Missed critical alerts                | Multi-channel delivery, retries, escalation       |
+| System Downtime                | Complete warning service interruption | Redundancy, failover, automated incident response |
+| Slow System Response           | Delayed warnings compromising safety | Performance monitoring, scaling infrastructure    |
+| Unauthorized Access            | Compromise of safety controls        | Role-based access control, audit logging          |
+
+Robust logging, alerting, and incident management provide rapid identification and remediation of failure events to maintain system integrity.
+
+---
+
+# End of Documentation

src/warnings/GlucoseReadingWarning.ts

@@ -0,0 +1,100 @@
+```typescript
+type GlucoseReading = {
+  timestamp: number; // Unix ms timestamp
+  value: number; // mg/dL or mmol/L, depending on usage context
+};
+
+type WarningLevel = 'none' | 'info' | 'warning' | 'critical';
+
+interface Warning {
+  level: WarningLevel;
+  message: string;
+  readingTimestamp?: number;
+  agedByMs?: number;
+}
+
+export class GlucoseReadingWarning {
+  private maxAgeMs: number;
+  private escalationThresholdsMs: { info: number; warning: number; critical: number };
+  private readingsHistory: GlucoseReading[];
+  private latestTimestamp: number | null;
+
+  constructor(
+    maxAgeMinutes: number = 10,
+    escalationThresholdsMinutes: { info: number; warning: number; critical: number } = {
+      info: 5,
+      warning: 10,
+      critical: 15,
+    }
+  ) {
+    this.maxAgeMs = maxAgeMinutes * 60 * 1000;
+    this.escalationThresholdsMs = {
+      info: escalationThresholdsMinutes.info * 60 * 1000,
+      warning: escalationThresholdsMinutes.warning * 60 * 1000,
+      critical: escalationThresholdsMinutes.critical * 60 * 1000,
+    };
+    this.readingsHistory = [];
+    this.latestTimestamp = null;
+  }
+
+  addReading(reading: GlucoseReading): void {
+    if (typeof reading.timestamp !== 'number' || Number.isNaN(reading.timestamp)) return;
+    if (typeof reading.value !== 'number' || Number.isNaN(reading.value)) return;
+
+    this.latestTimestamp = !this.latestTimestamp || reading.timestamp > this.latestTimestamp ? reading.timestamp : this.latestTimestamp;
+    this.readingsHistory.push(reading);
+    // Prune history older than maxAgeMs * 3 to keep size manageable
+    const threshold = Date.now() - this.maxAgeMs * 3;
+    this.readingsHistory = this.readingsHistory.filter(r => r.timestamp >= threshold);
+  }
+
+  getLatestReading(): GlucoseReading | null {
+    if (!this.latestTimestamp) return null;
+    return this.readingsHistory.reduce((latest, r) => (r.timestamp === this.latestTimestamp ? r : latest), null as GlucoseReading | null);
+  }
+
+  checkStaleness(currentTime: number = Date.now()): Warning {
+    if (!this.latestTimestamp) {
+      return {
+        level: 'critical',
+        message: 'No glucose readings have been received.',
+      };
+    }
+
+    const ageMs = currentTime - this.latestTimestamp;
+
+    if (ageMs < this.escalationThresholdsMs.info) {
+      return { level: 'none', message: 'Glucose readings are current.', readingTimestamp: this.latestTimestamp, agedByMs: ageMs };
+    }
+
+    if (ageMs < this.escalationThresholdsMs.warning) {
+      return {
+        level: 'info',
+        message: `Glucose reading is slightly stale (last received ${(ageMs / 60000).toFixed(1)} minutes ago).`,
+        readingTimestamp: this.latestTimestamp,
+        agedByMs: ageMs,
+      };
+    }
+
+    if (ageMs < this.escalationThresholdsMs.critical) {
+      return {
+        level: 'warning',
+        message: `Glucose reading is stale (last received ${(ageMs / 60000).toFixed(1)} minutes ago). Consider checking your device connection.`,
+        readingTimestamp: this.latestTimestamp,
+        agedByMs: ageMs,
+      };
+    }
+
+    return {
+      level: 'critical',
+      message: `Glucose reading is critically outdated (last received ${(ageMs / 60000).toFixed(1)} minutes ago). Immediate action required!`,
+      readingTimestamp: this.latestTimestamp,
+      agedByMs: ageMs,
+    };
+  }
+
+  getReadingHistory(sinceMs: number = Date.now() - this.maxAgeMs * 3): GlucoseReading[] {
+    return this.readingsHistory.filter(r => r.timestamp >= sinceMs);
+  }
+}
+```