feat: implement tip discrepancy detection and integrate it across the application

Author: heskew

CLAUDE.md

@@ -92,13 +92,14 @@ See `docs/FEATURES.md` for comprehensive feature list.
 
 ## Detection Algorithms
 
-See `docs/DETECTION.md` for algorithm details. Six algorithms:
+See `docs/DETECTION.md` for algorithm details. Seven algorithms:
 - Zombie Detection - forgotten recurring charges
 - Price Increase Detection - subscription price changes
 - Duplicate Detection - multiple services in same category
 - Auto-Cancellation Detection - stopped subscriptions
 - Resume Detection - reactivated subscriptions
 - Spending Anomaly Detection - unusual spending patterns
+- Tip Discrepancy Detection - bank amount higher than receipt total
 
 ## AI Integration
 

crates/hone-core/src/db/alerts.rs

@@ -223,6 +223,7 @@ impl Database {
                         "duplicate" => AlertType::Duplicate,
                         "resume" => AlertType::Resume,
                         "spending_anomaly" => AlertType::SpendingAnomaly,
+                        "tip_discrepancy" => AlertType::TipDiscrepancy,
                         _ => AlertType::Zombie,
                     },
                     subscription_id: row.get(2)?,
@@ -271,6 +272,7 @@ impl Database {
                         "duplicate" => AlertType::Duplicate,
                         "resume" => AlertType::Resume,
                         "spending_anomaly" => AlertType::SpendingAnomaly,
+                        "tip_discrepancy" => AlertType::TipDiscrepancy,
                         _ => AlertType::Zombie,
                     },
                     subscription_id: row.get(2)?,

crates/hone-core/src/db/import_history.rs

@@ -45,6 +45,8 @@ impl Database {
         price_increases_detected: i64,
         duplicates_detected: i64,
         receipts_matched: i64,
+        spending_anomalies_detected: i64,
+        tip_discrepancies_detected: i64,
     ) -> Result<()> {
         let conn = self.conn()?;
         conn.execute(
@@ -62,7 +64,9 @@ impl Database {
                 zombies_detected = ?,
                 price_increases_detected = ?,
                 duplicates_detected = ?,
-                receipts_matched = ?
+                receipts_matched = ?,
+                spending_anomalies_detected = ?,
+                tip_discrepancies_detected = ?
             WHERE id = ?
             "#,
             params![
@@ -79,6 +83,8 @@ impl Database {
                 price_increases_detected,
                 duplicates_detected,
                 receipts_matched,
+                spending_anomalies_detected,
+                tip_discrepancies_detected,
                 session_id,
             ],
         )?;
@@ -250,6 +256,7 @@ impl Database {
                    s.tagged_by_bank_category, s.tagged_fallback,
                    s.subscriptions_found, s.zombies_detected, s.price_increases_detected,
                    s.duplicates_detected, s.receipts_matched,
+                   s.spending_anomalies_detected, s.tip_discrepancies_detected,
                    s.user_email, s.ollama_model,
                    s.status, s.processing_phase, s.processing_current, s.processing_total, s.processing_error,
                    s.tagging_duration_ms, s.normalizing_duration_ms, s.matching_duration_ms,
@@ -404,24 +411,26 @@ impl Database {
                 price_increases_detected: row.get(15)?,
                 duplicates_detected: row.get(16)?,
                 receipts_matched: row.get(17)?,
-                user_email: row.get(18)?,
-                ollama_model: row.get(19)?,
+                spending_anomalies_detected: row.get(18)?,
+                tip_discrepancies_detected: row.get(19)?,
+                user_email: row.get(20)?,
+                ollama_model: row.get(21)?,
                 status: status_str
                     .as_deref()
                     .and_then(|s| s.parse().ok())
                     .unwrap_or(ImportStatus::Pending),
                 processing_phase: row.get(21)?,
                 processing_current: row.get::<_, Option<i64>>(22)?.unwrap_or(0),
-                processing_total: row.get::<_, Option<i64>>(23)?.unwrap_or(0),
-                processing_error: row.get(24)?,
-                tagging_duration_ms: row.get(25)?,
-                normalizing_duration_ms: row.get(26)?,
-                matching_duration_ms: row.get(27)?,
-                detecting_duration_ms: row.get(28)?,
-                total_duration_ms: row.get(29)?,
+                processing_total: row.get::<_, Option<i64>>(25)?.unwrap_or(0),
+                processing_error: row.get(26)?,
+                tagging_duration_ms: row.get(27)?,
+                normalizing_duration_ms: row.get(28)?,
+                matching_duration_ms: row.get(29)?,
+                detecting_duration_ms: row.get(30)?,
+                total_duration_ms: row.get(31)?,
                 created_at: parse_datetime(&created_at_str),
             },
-            account_name: row.get(31)?,
+            account_name: row.get(33)?,
         })
     }
 
@@ -583,9 +592,11 @@ impl Database {
             price_increases_detected,
             duplicates_detected,
             receipts_matched,
-        ): (i64, i64, i64, i64, i64) = conn.query_row(
+            spending_anomalies_detected,
+            tip_discrepancies_detected,
+        ): (i64, i64, i64, i64, i64, i64, i64) = conn.query_row(
             r#"SELECT subscriptions_found, zombies_detected, price_increases_detected,
-                      duplicates_detected, receipts_matched
+                      duplicates_detected, receipts_matched, spending_anomalies_detected, tip_discrepancies_detected
                FROM import_sessions WHERE id = ?"#,
             params![session_id],
             |row| {
@@ -595,6 +606,8 @@ impl Database {
                     row.get(2)?,
                     row.get(3)?,
                     row.get(4)?,
+                    row.get(5)?,
+                    row.get(6)?,
                 ))
             },
         )?;
@@ -637,6 +650,8 @@ impl Database {
             price_increases_detected,
             duplicates_detected,
             receipts_matched,
+            spending_anomalies_detected,
+            tip_discrepancies_detected,
             sample_transactions,
         })
     }
@@ -660,6 +675,8 @@ impl Database {
             "price_increases_detected": snapshot.price_increases_detected,
             "duplicates_detected": snapshot.duplicates_detected,
             "receipts_matched": snapshot.receipts_matched,
+            "spending_anomalies_detected": snapshot.spending_anomalies_detected,
+            "tip_discrepancies_detected": snapshot.tip_discrepancies_detected,
         })
         .to_string();
 

crates/hone-core/src/db/mod.rs

@@ -601,6 +601,8 @@ impl Database {
                 price_increases_detected INTEGER DEFAULT 0,
                 duplicates_detected INTEGER DEFAULT 0,
                 receipts_matched INTEGER DEFAULT 0,
+                spending_anomalies_detected INTEGER DEFAULT 0,
+                tip_discrepancies_detected INTEGER DEFAULT 0,
                 -- Metadata
                 user_email TEXT,
                 ollama_model TEXT,                          -- Ollama model used for tagging/normalization (if any)

crates/hone-core/src/db/receipts.rs

@@ -203,11 +203,32 @@ impl Database {
 
     /// Link receipt to transaction
     pub fn link_receipt_to_transaction(&self, receipt_id: i64, transaction_id: i64) -> Result<()> {
-        let conn = self.conn()?;
-        conn.execute(
+        let mut conn = self.conn()?;
+
+        // Get receipt total to update transaction's expected_amount
+        let receipt_total: Option<f64> = conn
+            .query_row(
+                "SELECT receipt_total FROM receipts WHERE id = ?",
+                params![receipt_id],
+                |row| row.get(0),
+            )
+            .optional()?;
+
+        let tx = conn.transaction()?;
+
+        tx.execute(
             "UPDATE receipts SET transaction_id = ?, status = 'matched' WHERE id = ?",
             params![transaction_id, receipt_id],
         )?;
+
+        if let Some(total) = receipt_total {
+            tx.execute(
+                "UPDATE transactions SET expected_amount = ? WHERE id = ?",
+                params![total, transaction_id],
+            )?;
+        }
+
+        tx.commit()?;
         Ok(())
     }
 

crates/hone-core/src/detect.rs

@@ -59,6 +59,8 @@ pub struct DetectionConfig {
     /// Days after which an acknowledgment is considered stale and the subscription
     /// may be flagged as a zombie again (0 = never stale)
     pub acknowledgment_stale_days: i64,
+    /// Threshold for tip discrepancy detection (absolute dollars)
+    pub tip_discrepancy_threshold: f64,
 }
 
 impl Default for DetectionConfig {
@@ -79,6 +81,7 @@ impl Default for DetectionConfig {
             spending_anomaly_min_baseline: 50.0, // Only flag if baseline >= $50/month
             // Re-acknowledgment defaults
             acknowledgment_stale_days: 90, // Re-check after 90 days (~quarterly)
+            tip_discrepancy_threshold: 0.50, // Flag if diff > $0.50
         }
     }
 }
@@ -93,6 +96,7 @@ pub struct DetectionResults {
     pub auto_cancelled: usize,
     pub resumes_detected: usize,
     pub spending_anomalies_detected: usize,
+    pub tip_discrepancies_detected: usize,
 }
 
 /// Main detector that runs all algorithms
@@ -204,10 +208,11 @@ impl<'a> WasteDetector<'a> {
         let spending_anomalies_detected = self
             .detect_spending_anomalies_with_progress(progress)
             .await?;
+        let tip_discrepancies_detected = self.detect_tip_discrepancies()?;
 
         info!(
-            "Detection complete: {} subscriptions, {} auto-cancelled, {} resumed, {} zombies, {} price increases, {} duplicates, {} spending anomalies",
-            subscriptions_found, auto_cancelled, resumes_detected, zombies_detected, price_increases_detected, duplicates_detected, spending_anomalies_detected
+            "Detection complete: {} subscriptions, {} auto-cancelled, {} resumed, {} zombies, {} price increases, {} duplicates, {} spending anomalies, {} tip discrepancies",
+            subscriptions_found, auto_cancelled, resumes_detected, zombies_detected, price_increases_detected, duplicates_detected, spending_anomalies_detected, tip_discrepancies_detected
         );
 
         Ok(DetectionResults {
@@ -218,6 +223,7 @@ impl<'a> WasteDetector<'a> {
             auto_cancelled,
             resumes_detected,
             spending_anomalies_detected,
+            tip_discrepancies_detected,
         })
     }
 
@@ -829,6 +835,38 @@ impl<'a> WasteDetector<'a> {
         Ok(count)
     }
 
+    /// Detect transactions where the amount is higher than the receipt total
+    fn detect_tip_discrepancies(&self) -> Result<usize> {
+        let transactions = self.db.list_transactions(None, 10000, 0)?;
+        let mut count = 0;
+
+        for tx in transactions {
+            let expected = match tx.expected_amount {
+                Some(e) => e.abs(),
+                None => continue,
+            };
+
+            let actual = tx.amount.abs();
+            let diff = actual - expected;
+
+            if diff > self.config.tip_discrepancy_threshold {
+                let message = format!(
+                    "{} charge of ${:.2} is higher than receipt total of ${:.2} (potential tip: ${:.2})",
+                    tx.merchant_normalized.as_deref().unwrap_or(&tx.description),
+                    actual,
+                    expected,
+                    diff
+                );
+
+                self.db
+                    .create_alert(AlertType::TipDiscrepancy, None, Some(&message))?;
+                count += 1;
+            }
+        }
+
+        Ok(count)
+    }
+
     /// Detect spending anomalies
     ///
     /// Compares current month spending by category against a 3-month rolling baseline.
@@ -2091,4 +2129,62 @@ mod tests {
         assert_eq!(config.smart_min_transactions, 2);
         assert_eq!(config.ollama_confidence_threshold, 0.7);
     }
+
+    #[tokio::test]
+    async fn test_detect_tip_discrepancy() {
+        let db = Database::in_memory().unwrap();
+
+        // Create account
+        let account_id = db
+            .upsert_account("Test Account", crate::models::Bank::Chase, None)
+            .unwrap();
+
+        // Create a transaction with an expected amount (e.g. from a receipt)
+        // Bank amount: $55.00
+        // Receipt total: $45.00
+        // Expected amount: $45.00
+        let tx_id = db
+            .insert_transaction(
+                account_id,
+                &crate::models::NewTransaction {
+                    date: Utc::now().date_naive(),
+                    description: "RESTO BAR".to_string(),
+                    amount: -55.00,
+                    category: Some("Dining".to_string()),
+                    import_hash: "tip_test_hash".to_string(),
+                    original_data: None,
+                    import_format: None,
+                    card_member: None,
+                    payment_method: None,
+                },
+            )
+            .unwrap()
+            .unwrap();
+
+        // Manually set expected_amount as if a receipt was linked
+        let conn = db.conn().unwrap();
+        conn.execute(
+            "UPDATE transactions SET expected_amount = 45.00 WHERE id = ?",
+            [tx_id],
+        )
+        .unwrap();
+
+        let detector = WasteDetector::new(&db);
+        let results = detector.detect_all().await.unwrap();
+
+        // Should have detected 1 tip discrepancy
+        assert_eq!(results.tip_discrepancies_detected, 1);
+
+        // Verify a tip discrepancy alert was created
+        let alerts = db.list_alerts(false).unwrap();
+        let tip_alert = alerts
+            .iter()
+            .find(|a| a.alert_type == AlertType::TipDiscrepancy)
+            .expect("Should have created a tip discrepancy alert");
+        
+        assert!(tip_alert.message.as_ref().unwrap().contains("RESTO BAR"));
+        assert!(tip_alert.message.as_ref().unwrap().contains("$55.00"));
+        assert!(tip_alert.message.as_ref().unwrap().contains("$45.00"));
+        assert!(tip_alert.message.as_ref().unwrap().contains("potential tip: $10.00"));
+    }
 }

crates/hone-core/src/models.rs

@@ -315,6 +315,8 @@ pub enum AlertType {
     Resume,
     /// Spending in a category changed dramatically vs baseline
     SpendingAnomaly,
+    /// Transaction amount is higher than receipt total (e.g. unrecorded tip)
+    TipDiscrepancy,
 }
 
 impl AlertType {
@@ -325,6 +327,7 @@ impl AlertType {
             Self::Duplicate => "duplicate",
             Self::Resume => "resume",
             Self::SpendingAnomaly => "spending_anomaly",
+            Self::TipDiscrepancy => "tip_discrepancy",
         }
     }
 
@@ -335,6 +338,7 @@ impl AlertType {
             Self::Duplicate => "Duplicate Service",
             Self::Resume => "Subscription Resumed",
             Self::SpendingAnomaly => "Spending Change",
+            Self::TipDiscrepancy => "Tip Discrepancy",
         }
     }
 
@@ -345,6 +349,7 @@ impl AlertType {
             Self::Duplicate => "You have multiple services in this category",
             Self::Resume => "A subscription you cancelled has started charging again",
             Self::SpendingAnomaly => "Your spending in this category changed significantly",
+            Self::TipDiscrepancy => "This transaction is higher than your receipt total",
         }
     }
 }
@@ -1512,6 +1517,8 @@ pub struct ImportSession {
     pub price_increases_detected: i64,
     pub duplicates_detected: i64,
     pub receipts_matched: i64,
+    pub spending_anomalies_detected: i64,
+    pub tip_discrepancies_detected: i64,
     // Metadata
     pub user_email: Option<String>,
     pub ollama_model: Option<String>,
@@ -1754,6 +1761,8 @@ pub struct ReprocessSnapshot {
     pub price_increases_detected: i64,
     pub duplicates_detected: i64,
     pub receipts_matched: i64,
+    pub spending_anomalies_detected: i64,
+    pub tip_discrepancies_detected: i64,
     /// Sample of transactions with their current tags for change detection
     pub sample_transactions: Vec<TransactionTagSnapshot>,
 }
@@ -1930,6 +1939,8 @@ pub struct DetectionResultsDiff {
     pub price_increases_diff: i64,
     pub duplicates_diff: i64,
     pub receipts_matched_diff: i64,
+    pub spending_anomalies_diff: i64,
+    pub tip_discrepancies_diff: i64,
 }
 
 /// A transaction's tag difference between two runs