# Project Handoff - 2026-03-19

## Scope

This handoff covers two related workstreams:

1. WhatsApp multi-message burst reply flow
2. Email thread-aware burst reply flow

The goal in both channels was to stop replying once per inbound fragment and instead:

- buffer closely spaced inbound messages
- generate one reply for the full burst
- apply lead status once per burst
- cancel pending AI reply work if any outbound message is sent first
- keep a DB-backed thread memory for better future repliesrs
## Current Status

### WhatsApp

Implemented and validated:

- burst buffer model
- webhook refactor to queue inbound bursts instead of immediately replying
- burst worker/cron
- cancellation hooks
- burst-level status handling
- prompt/history refactor
- DB-backed thread summary
- cross-source summary context
- ownership handling
- observability and failure telemetry
- test coverage

Validated earlier:

- full test suite passed
- staging smoke validation passed
- failed burst investigation completed
- structured `failureMeta` capture added for future Meta `400` failures

Remaining for WhatsApp:

- no known in-scope implementation gap from this feature set
- only post-deploy observation remains for newly added `failureMeta` on a future real staging failure

### Email

Implemented so far:

- phase 1: burst model, inbound processor refactor, worker
- phase 2: outbound cancellation hooks and legacy bypass cron cleanup
- phase 3: burst-aware prompt/history refactor
- phase 4: DB-backed email thread summary plus cross-source summary memory

Not yet done:

- phase 5: ownership/audit polish, retention cleanup, and broader integration coverage for email
- live staging validation for the new email burst flow

## Final Agreed Product Behavior

### WhatsApp

- buffer inbound WhatsApp messages into one burst
- fixed 30-second window from the first message in that burst
- include everything received up to that deadline
- anything after that starts a new burst
- DB-backed burst queue and thread summary
- worker polls every 2 seconds
- apply status once per full burst
- use protected-status rules
- summary plus recent-window prompt design
- cross-source summary from WhatsApp + email + CRM notes

### Email

- buffer inbound emails per thread
- wait 2 minutes from the first inbound email in the burst
- do not extend the window on later inbound emails
- send one combined natural email reply for the whole burst
- any new inbound after reply starts a new burst
- cancel pending burst on any outbound email:
  - manual
  - AI
  - campaign
  - follow-up
- apply lead status once per full burst
- use the same protected-status rules as WhatsApp
- worker polls every 10 seconds
- use DB-backed email thread summary memory
- cross-source summary uses:
  - current email burst
  - recent same-thread email history
  - recent WhatsApp summary
  - CRM notes

## Key Files

### WhatsApp

- `models/whatsapp.burst.model.js`
- `models/whatsapp.thread.summary.model.js`
- `services/whatsappBurst.service.js`
- `corns/whatsappBurstCron.js`
- `routes/waba.route.js`
- `whatsappBurstTestRunner.js`
- `whatsappBurstIntegrationTestRunner.js`

### Email

- `models/email.burst.model.js`
- `models/email.thread.summary.model.js`
- `services/emailBurst.service.js`
- `services/emailPromptBuilder.js`
- `services/emailThreadSummary.service.js`
- `services/imapResponse.js`
- `services/emailController.js`
- `services/emailtemplateSender.js`
- `services/sendEngine.js`
- `corns/emailBurstCron.js`
- `corns/corns.js`
- `emailBurstTestRunner.js`
- `emailPromptBuilderTestRunner.js`
- `emailThreadSummaryTestRunner.js`

## Important Implementation Notes

### WhatsApp notes

- `failureMeta` is now persisted for structured send failures instead of only storing a generic `status code 400`
- two historical failed staging bursts were traced to Meta send failures, not burst assembly or AI generation
- prompt/history and summary logic were already refactored into burst-aware flow

### Email notes

- inbound email now queues a burst and returns early; the old immediate-reply code is still physically present lower in `services/imapResponse.js` but unreachable after the new queue path
- duplicate legacy email cron paths that could bypass the burst system were removed from `corns/corns.js`
- email thread summary uses lazy OpenAI client initialization so tests do not fail when `OPENAI_API_KEY` is absent
- summary update is best-effort and should not block sending the actual email reply

## Validation Status

Latest validated state:

- `npm test` passes

Current `package.json` test chain:

- `leadOutcomeTestRunner.js`
- `campaignAutomationTestRunner.js`
- `emailPromptBuilderTestRunner.js`
- `emailThreadSummaryTestRunner.js`
- `emailBurstTestRunner.js`
- `whatsappBurstTestRunner.js`
- `whatsappBurstIntegrationTestRunner.js`

## Remaining Work

### Email Phase 5

Recommended next implementation bucket:

1. Ownership and audit polish
- make ownership history on email as complete and explicit as WhatsApp
- confirm owner changes while a burst is pending/processing are recorded cleanly

2. Retention and cleanup
- add cleanup job for old email burst records, similar to WhatsApp retention goals
- define retention for email thread summaries if needed

3. Broader integration coverage
- add more end-to-end tests for:
  - owner changes during pending bursts
  - retries
  - summary update behavior
  - outbound cancellation races
  - status transitions on full email bursts

4. Live staging validation
- verify real inbound email burst buffering
- verify cancellation on outbound sends
- verify email thread summary documents are created and updated
- verify prompt snapshots and summary state fields persist correctly

## Recommended Next Step For Another Engineer

If another engineer picks this up, the best next action is:

1. review the email phase 4 files listed above
2. implement email phase 5
3. deploy to staging
4. run live validation for the email burst flow

## Short Handoff Summary

WhatsApp burst behavior is implemented end to end and validated. Email burst behavior is implemented through phase 4, including prompt/history refactor and DB-backed thread memory, and is passing tests locally. The main unfinished area is email phase 5 plus live staging validation.