@push.rocks/smartmta 7.0.0 → 8.0.0

package/ts/mail/delivery/classes.delivery.queue.ts

@@ -1,16 +1,57 @@
 import { EventEmitter } from 'node:events';
+import { createHash } from 'node:crypto';
 import { deserialize, serialize } from 'node:v8';
 import type { IBlobStorageManager } from '../interfaces.storage.js';
 import { logger } from '../../logger.js';
 import { type EmailProcessingMode } from './interfaces.js';
+import type { ISmtpTransactionAttempt } from './interfaces.js';
+import {
+  normalizeSmtpTranscript,
+  SMTP_TRANSCRIPT_MAX_ENTRIES,
+  SMTP_TRANSCRIPT_MAX_ENTRY_CODE_POINTS,
+  SMTP_TRANSCRIPT_MAX_UTF8_BYTES,
+} from '../../security/classes.rustsecuritybridge.js';
 import type { IEmailRoute } from '../routing/interfaces.js';
 import { Email, type IEmailOptions } from '../core/classes.email.js';
+import { emitSafely } from './functions.safe-observers.js';
+import { getErrorMessage } from '../../functions.errors.js';
 
 /**
  * Queue item status
  */
 export type QueueItemStatus = 'pending' | 'processing' | 'delivered' | 'failed' | 'deferred';
 
+export type TRecipientDeliveryState = 'unresolved' | 'delivered' | 'permanentFailure';
+
+export interface IRecipientDeliveryState {
+  recipient: string;
+  normalizedRecipient: string;
+  state: TRecipientDeliveryState;
+  smtpCode?: number;
+  smtpResponse?: string;
+  updatedAt: Date;
+}
+
+export interface IRecipientPermanentFailure {
+  recipient: string;
+  smtpCode: number;
+  smtpResponse: string;
+}
+
+export interface IBounceOperation {
+  operationId: string;
+  kind: 'smtpFailure';
+  recipient: string;
+  normalizedRecipient: string;
+  smtpCode: number;
+  smtpResponse: string;
+  state: 'pending' | 'completed';
+  attempts: number;
+  nextAttempt: Date;
+  lastError?: string;
+  completedAt?: Date;
+}
+
 /**
  * Queue item interface
  */
@@ -26,6 +67,11 @@ export interface IQueueItem {
   createdAt: Date;
   updatedAt: Date;
   deliveredAt?: Date;
+  deliveredRecipients?: string[];
+  terminalRecipients?: string[];
+  recipientStates?: IRecipientDeliveryState[];
+  bounceOperations?: IBounceOperation[];
+  smtpTransactions?: ISmtpTransactionAttempt[];
 }
 
 interface IStoredEmail {
@@ -34,7 +80,7 @@ interface IStoredEmail {
   envelopeFrom: string;
 }
 
-interface IStoredQueueItem {
+interface IStoredQueueItemV1 {
   schemaVersion: 1;
   id: string;
   processingMode: EmailProcessingMode;
@@ -47,6 +93,40 @@ interface IStoredQueueItem {
   createdAt: number;
   updatedAt: number;
   deliveredAt?: number;
+  deliveredRecipients?: string[];
+  terminalRecipients?: string[];
+  smtpTransactions?: ISmtpTransactionAttempt[];
+}
+
+interface IStoredRecipientDeliveryState extends Omit<IRecipientDeliveryState, 'updatedAt'> {
+  updatedAt: number;
+}
+
+interface IStoredBounceOperation extends Omit<IBounceOperation, 'nextAttempt' | 'completedAt'> {
+  nextAttempt: number;
+  completedAt?: number;
+}
+
+interface IStoredQueueItemV2 extends Omit<IStoredQueueItemV1, 'schemaVersion'> {
+  schemaVersion: 2;
+  recipientStates: IStoredRecipientDeliveryState[];
+  bounceOperations: IStoredBounceOperation[];
+}
+
+type IStoredQueueItem = IStoredQueueItemV1 | IStoredQueueItemV2;
+
+type TQueueLifecycleState = 'new' | 'initialized' | 'shutting-down' | 'closed';
+
+export interface IQueueFailureOptions {
+  /** Unknown failures default to retryable so temporary internal faults do not lose mail. */
+  retryable?: boolean;
+}
+
+export interface IQueueFailureTransition {
+  updated: boolean;
+  status?: 'deferred' | 'failed';
+  terminal: boolean;
+  terminalReason?: 'permanent' | 'retry_exhausted';
 }
 
 /**
@@ -110,6 +190,9 @@ export interface IQueueStats {
   processingActive: boolean;
 }
 
+const managedQueueOwners =
+  new WeakMap<IBlobStorageManager, Map<string, UnifiedDeliveryQueue>>();
+
 /**
  * A unified queue for all email modes
  */
@@ -131,6 +214,8 @@ export class UnifiedDeliveryQueue extends EventEmitter {
   private stats: IQueueStats;
   private processing: boolean = false;
   private totalProcessed: number = 0;
+  private ownsManagedPrefix = false;
+  private lifecycleState: TQueueLifecycleState = 'new';
   
   /**
    * Create a new unified delivery queue
@@ -178,26 +263,98 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       processingActive: false
     };
   }
+
+  private assertMutable(): void {
+    if (this.lifecycleState === 'shutting-down' || this.lifecycleState === 'closed') {
+      throw new Error(`Delivery queue is ${this.lifecycleState}; mutations are no longer allowed`);
+    }
+  }
+
+  private createInitialRecipientStates(email: Email): IRecipientDeliveryState[] {
+    const byRecipient = new Map<string, IRecipientDeliveryState>();
+    const now = new Date();
+    for (const recipient of email.getAllRecipients()) {
+      const normalizedRecipient = recipient.trim().toLowerCase();
+      if (!normalizedRecipient || byRecipient.has(normalizedRecipient)) continue;
+      byRecipient.set(normalizedRecipient, {
+        recipient,
+        normalizedRecipient,
+        state: 'unresolved',
+        updatedAt: now,
+      });
+    }
+    return [...byRecipient.values()];
+  }
+
+  private createBounceOperationId(itemId: string, normalizedRecipient: string): string {
+    return createHash('sha256')
+      .update(itemId)
+      .update('\0')
+      .update(normalizedRecipient)
+      .update('\0smtpFailure')
+      .digest('hex');
+  }
   
   /**
    * Initialize the queue
    */
-  public async initialize(): Promise<void> {
+  private claimManagedPrefix(): void {
+    const storageManager = this.options.storageManager;
+    if (!storageManager || this.ownsManagedPrefix) return;
+    let owners = managedQueueOwners.get(storageManager);
+    if (!owners) {
+      owners = new Map();
+      managedQueueOwners.set(storageManager, owners);
+    }
+    const existingOwner = owners.get(this.options.storagePrefix);
+    if (existingOwner && existingOwner !== this) {
+      throw new Error(
+        `Managed queue prefix ${this.options.storagePrefix} already has an active delivery owner`,
+      );
+    }
+    owners.set(this.options.storagePrefix, this);
+    this.ownsManagedPrefix = true;
+  }
+
+  private releaseManagedPrefix(): void {
+    const storageManager = this.options.storageManager;
+    if (!storageManager || !this.ownsManagedPrefix) return;
+    const owners = managedQueueOwners.get(storageManager);
+    if (owners?.get(this.options.storagePrefix) === this) {
+      owners.delete(this.options.storagePrefix);
+      if (owners.size === 0) managedQueueOwners.delete(storageManager);
+    }
+    this.ownsManagedPrefix = false;
+  }
+
+  public async initialize(optionsArg: { startProcessing?: boolean } = {}): Promise<void> {
     logger.log('info', 'Initializing UnifiedDeliveryQueue');
-    
+
+    if (this.lifecycleState !== 'new') {
+      throw new Error(`Delivery queue cannot initialize from ${this.lifecycleState} state`);
+    }
+
+    this.claimManagedPrefix();
     try {
       if (this.options.storageManager) {
         await this.loadFromStorage();
       }
+      this.lifecycleState = 'initialized';
       
-      // Start the queue processing timer
-      this.startProcessing();
+      // Embedders may hydrate durable state before delivery dependencies are ready.
+      if (optionsArg.startProcessing !== false) {
+        this.startProcessing();
+      }
       
       // Emit initialized event
-      this.emit('initialized');
+      await emitSafely(this, 'initialized');
       logger.log('info', 'UnifiedDeliveryQueue initialized successfully');
     } catch (error) {
-      logger.log('error', `Failed to initialize queue: ${error.message}`);
+      this.queue.clear();
+      this.updateStats();
+      this.lifecycleState = 'new';
+      this.releaseManagedPrefix();
+      logger.log('error', `Failed to initialize queue: ${(error as Error).message}`);
       throw error;
     }
   }
@@ -224,7 +381,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
     this.processing = true;
     this.stats.processingActive = true;
-    this.emit('processingStarted');
+    void emitSafely(this, 'processingStarted');
     logger.log('info', 'Queue processing started');
   }
   
@@ -243,7 +400,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
     this.processing = false;
     this.stats.processingActive = false;
-    this.emit('processingStopped');
+    void emitSafely(this, 'processingStopped');
     logger.log('info', 'Queue processing stopped');
   }
   
@@ -270,14 +427,14 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       readyItems.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
       
       // Emit event for ready items
-      this.emit('itemsReady', readyItems);
+      await emitSafely(this, 'itemsReady', readyItems);
       logger.log('info', `Found ${readyItems.length} items ready for processing`);
       
       // Update statistics
       this.updateStats();
     } catch (error) {
-      logger.log('error', `Error processing queue: ${error.message}`);
-      this.emit('error', error);
+      logger.log('error', `Error processing queue: ${getErrorMessage(error)}`);
+      await emitSafely(this, 'error', error);
     }
   }
   
@@ -292,6 +449,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     mode: EmailProcessingMode,
     route?: IEmailRoute,
   ): Promise<string> {
+    this.assertMutable();
     if (!(processingResult instanceof Email)) {
       throw new Error('Queue processingResult must be an Email instance');
     }
@@ -314,7 +472,12 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       attempts: 0,
       nextAttempt: new Date(),
       createdAt: new Date(),
-      updatedAt: new Date()
+      updatedAt: new Date(),
+      deliveredRecipients: [],
+      terminalRecipients: [],
+      recipientStates: this.createInitialRecipientStates(processingResult),
+      bounceOperations: [],
+      smtpTransactions: [],
     };
     
     // Commit durable state before exposing the item in memory or emitting acceptance.
@@ -325,7 +488,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     this.updateStats();
     
     // Emit event
-    this.emit('itemEnqueued', item);
+    await emitSafely(this, 'itemEnqueued', item);
     logger.log('info', `Item enqueued with ID ${id}, mode: ${mode}`);
     
     return id;
@@ -340,7 +503,19 @@ export class UnifiedDeliveryQueue extends EventEmitter {
   }
 
   public listItems(): IQueueItem[] {
-    return Array.from(this.queue.values()).map((item) => ({ ...item }));
+    return Array.from(this.queue.values()).map((item) => ({
+      ...item,
+      deliveredRecipients: [...(item.deliveredRecipients || [])],
+      terminalRecipients: [...(item.terminalRecipients || [])],
+      recipientStates: (item.recipientStates || []).map((state) => ({ ...state })),
+      bounceOperations: (item.bounceOperations || []).map((operation) => ({ ...operation })),
+      smtpTransactions: (item.smtpTransactions || []).map((transaction) => ({
+        ...transaction,
+        recipients: [...transaction.recipients],
+        recipientResults: transaction.recipientResults?.map((result) => ({ ...result })),
+        transcript: transaction.transcript.map((entry) => ({ ...entry })),
+      })),
+    }));
   }
   
   /**
@@ -348,9 +523,16 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * @param id Item ID
    */
   public async markProcessing(id: string): Promise<boolean> {
+    this.assertMutable();
     const item = this.queue.get(id);
     
-    if (!item) {
+    if (
+      !item
+      || !(
+        item.status === 'pending'
+        || (item.status === 'deferred' && item.nextAttempt <= new Date())
+      )
+    ) {
       return false;
     }
     
@@ -364,7 +546,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     this.updateStats();
     
     // Emit event
-    this.emit('itemProcessing', item);
+    await emitSafely(this, 'itemProcessing', item);
     logger.log('info', `Item ${id} marked as processing, attempt ${item.attempts}`);
     
     return true;
@@ -375,9 +557,10 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * @param id Item ID
    */
   public async markDelivered(id: string): Promise<boolean> {
+    this.assertMutable();
     const item = this.queue.get(id);
     
-    if (!item) {
+    if (!item || item.status === 'delivered' || item.status === 'failed') {
       return false;
     }
     
@@ -392,7 +575,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     this.updateStats();
     
     // Emit event
-    this.emit('itemDelivered', item);
+    await emitSafely(this, 'itemDelivered', item);
     logger.log('info', `Item ${id} marked as delivered after ${item.attempts} attempts`);
     
     return true;
@@ -403,15 +586,37 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * @param id Item ID
    * @param error Error message
    */
-  public async markFailed(id: string, error: string): Promise<boolean> {
+  public async markFailed(
+    id: string,
+    error: string,
+    optionsArg: IQueueFailureOptions = {},
+  ): Promise<boolean> {
+    return (await this.markFailedWithTransition(id, error, optionsArg)).updated;
+  }
+
+  /** Rich internal disposition used by the delivery system without breaking markFailed(). */
+  public async markFailedWithTransition(
+    id: string,
+    error: string,
+    optionsArg: IQueueFailureOptions = {},
+  ): Promise<IQueueFailureTransition> {
+    this.assertMutable();
     const item = this.queue.get(id);
     
     if (!item) {
-      return false;
+      return { updated: false, terminal: false };
+    }
+    if (item.status === 'delivered' || item.status === 'failed') {
+      return {
+        updated: false,
+        status: item.status === 'failed' ? 'failed' : undefined,
+        terminal: true,
+      };
     }
     
     // Determine if we should retry
-    if (item.attempts < this.options.maxRetries) {
+    const retryable = optionsArg.retryable !== false;
+    if (retryable && item.attempts < this.options.maxRetries) {
       // Calculate next retry time with exponential backoff
       const delay = Math.min(
         this.options.baseRetryDelay * Math.pow(2, item.attempts - 1),
@@ -426,8 +631,10 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       });
       
       // Emit event
-      this.emit('itemDeferred', item);
+      await emitSafely(this, 'itemDeferred', item);
       logger.log('info', `Item ${id} deferred for ${delay}ms, attempt ${item.attempts}, error: ${error}`);
+      this.updateStats();
+      return { updated: true, status: 'deferred', terminal: false };
     } else {
       // Mark as permanently failed
       await this.applyPersistedMutation(item, (updatedItem) => {
@@ -440,21 +647,237 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       this.totalProcessed++;
       
       // Emit event
-      this.emit('itemFailed', item);
+      await emitSafely(this, 'itemFailed', item);
       logger.log('warn', `Item ${id} permanently failed after ${item.attempts} attempts, error: ${error}`);
     }
-    
-    // Update statistics
+
     this.updateStats();
-    
+    return {
+      updated: true,
+      status: 'failed',
+      terminal: true,
+      terminalReason: retryable ? 'retry_exhausted' : 'permanent',
+    };
+  }
+
+  /** Persist a completed SMTP attempt before any queue status event is emitted. */
+  public async appendSmtpTransaction(
+    id: string,
+    transaction: ISmtpTransactionAttempt,
+  ): Promise<boolean> {
+    this.assertMutable();
+    const item = this.queue.get(id);
+    if (!item) return false;
+    const normalizedTransaction: ISmtpTransactionAttempt = {
+      ...transaction,
+      queueItemId: id,
+      recipients: [...transaction.recipients],
+      recipientResults: transaction.recipientResults?.map((result) => ({ ...result })),
+      transcript: normalizeSmtpTranscript(transaction.transcript),
+    };
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      updatedItem.smtpTransactions = [
+        ...(updatedItem.smtpTransactions || []),
+        normalizedTransaction,
+      ].slice(-20);
+      updatedItem.updatedAt = new Date();
+    });
+    await emitSafely(this, 'smtpTransaction', item, normalizedTransaction);
     return true;
   }
-  
+
+  /** Record recipients accepted after the SMTP final-response 250 checkpoint. */
+  public async markRecipientsDelivered(id: string, recipients: string[]): Promise<boolean> {
+    this.assertMutable();
+    const item = this.queue.get(id);
+    if (!item) return false;
+    const normalizedRecipients = new Set(
+      recipients.map((recipient) => recipient.trim().toLowerCase()).filter(Boolean),
+    );
+    if (normalizedRecipients.size === 0) return false;
+
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      const states = updatedItem.recipientStates || this.createInitialRecipientStates(
+        updatedItem.processingResult,
+      );
+      const delivered = new Set(updatedItem.deliveredRecipients || []);
+      const now = new Date();
+      for (const state of states) {
+        if (
+          normalizedRecipients.has(state.normalizedRecipient)
+          && state.state === 'unresolved'
+        ) {
+          state.state = 'delivered';
+          state.updatedAt = now;
+          delete state.smtpCode;
+          delete state.smtpResponse;
+          delivered.add(state.normalizedRecipient);
+        }
+      }
+      updatedItem.recipientStates = states;
+      updatedItem.deliveredRecipients = [...delivered];
+      updatedItem.updatedAt = now;
+    });
+    return true;
+  }
+
+  /**
+   * Atomically checkpoint permanent recipient failures together with their
+   * durable bounce work. This is the sole 5xx recipient transition.
+   */
+  public async markRecipientsTerminal(
+    id: string,
+    failures: Array<string | IRecipientPermanentFailure>,
+  ): Promise<string[]> {
+    this.assertMutable();
+    const item = this.queue.get(id);
+    if (!item || failures.length === 0) return [];
+    const normalizedFailures = failures.map((failure) => (
+      typeof failure === 'string'
+        ? {
+            recipient: failure,
+            smtpCode: 550,
+            smtpResponse: 'SMTP recipient permanently rejected',
+          }
+        : failure
+    ));
+    const newlyTerminal: string[] = [];
+
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      const states = updatedItem.recipientStates || this.createInitialRecipientStates(
+        updatedItem.processingResult,
+      );
+      const terminal = new Set(updatedItem.terminalRecipients || []);
+      const operations = updatedItem.bounceOperations || [];
+      const operationIds = new Set(operations.map((operation) => operation.operationId));
+      const now = new Date();
+
+      for (const failure of normalizedFailures) {
+        const normalizedRecipient = failure.recipient.trim().toLowerCase();
+        const state = states.find(
+          (candidate) => candidate.normalizedRecipient === normalizedRecipient,
+        );
+        if (!state || state.state !== 'unresolved') continue;
+
+        state.state = 'permanentFailure';
+        state.smtpCode = failure.smtpCode;
+        state.smtpResponse = failure.smtpResponse;
+        state.updatedAt = now;
+        terminal.add(normalizedRecipient);
+        newlyTerminal.push(state.recipient);
+
+        const operationId = this.createBounceOperationId(updatedItem.id, normalizedRecipient);
+        if (!operationIds.has(operationId)) {
+          operations.push({
+            operationId,
+            kind: 'smtpFailure',
+            recipient: state.recipient,
+            normalizedRecipient,
+            smtpCode: failure.smtpCode,
+            smtpResponse: failure.smtpResponse,
+            state: 'pending',
+            attempts: 0,
+            nextAttempt: now,
+          });
+          operationIds.add(operationId);
+        }
+      }
+
+      updatedItem.recipientStates = states;
+      updatedItem.terminalRecipients = [...terminal];
+      updatedItem.bounceOperations = operations;
+      updatedItem.updatedAt = now;
+    });
+    return newlyTerminal;
+  }
+
+  public getRecipientDisposition(id: string): {
+    unresolved: string[];
+    delivered: string[];
+    permanentFailures: string[];
+  } {
+    const item = this.queue.get(id);
+    if (!item) return { unresolved: [], delivered: [], permanentFailures: [] };
+    const states = item.recipientStates || this.createInitialRecipientStates(item.processingResult);
+    return {
+      unresolved: states.filter((state) => state.state === 'unresolved').map((state) => state.recipient),
+      delivered: states.filter((state) => state.state === 'delivered').map((state) => state.recipient),
+      permanentFailures: states
+        .filter((state) => state.state === 'permanentFailure')
+        .map((state) => state.recipient),
+    };
+  }
+
+  /** Includes terminal queue items because bounce work outlives delivery status. */
+  public listPendingBounceOperations(
+    now: Date = new Date(),
+  ): Array<{ itemId: string; operation: IBounceOperation }> {
+    const result: Array<{ itemId: string; operation: IBounceOperation }> = [];
+    for (const item of this.queue.values()) {
+      for (const operation of item.bounceOperations || []) {
+        if (operation.state === 'pending' && operation.nextAttempt <= now) {
+          result.push({ itemId: item.id, operation: { ...operation } });
+        }
+      }
+    }
+    return result;
+  }
+
+  public async markBounceOperationCompleted(
+    itemId: string,
+    operationId: string,
+  ): Promise<boolean> {
+    this.assertMutable();
+    const item = this.queue.get(itemId);
+    const operation = item?.bounceOperations?.find(
+      (candidate) => candidate.operationId === operationId,
+    );
+    if (!item || !operation || operation.state === 'completed') return false;
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      const updatedOperation = updatedItem.bounceOperations?.find(
+        (candidate) => candidate.operationId === operationId,
+      );
+      if (!updatedOperation) return;
+      updatedOperation.state = 'completed';
+      updatedOperation.completedAt = new Date();
+      delete updatedOperation.lastError;
+      updatedItem.updatedAt = new Date();
+    });
+    return true;
+  }
+
+  public async markBounceOperationFailed(
+    itemId: string,
+    operationId: string,
+    error: string,
+  ): Promise<boolean> {
+    this.assertMutable();
+    const item = this.queue.get(itemId);
+    const operation = item?.bounceOperations?.find(
+      (candidate) => candidate.operationId === operationId,
+    );
+    if (!item || !operation || operation.state === 'completed') return false;
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      const updatedOperation = updatedItem.bounceOperations?.find(
+        (candidate) => candidate.operationId === operationId,
+      );
+      if (!updatedOperation) return;
+      updatedOperation.attempts++;
+      updatedOperation.lastError = error;
+      updatedOperation.nextAttempt = new Date(
+        Date.now() + Math.min(60_000 * (2 ** Math.max(0, updatedOperation.attempts - 1)), 3_600_000),
+      );
+      updatedItem.updatedAt = new Date();
+    });
+    return true;
+  }
+
   /**
    * Remove an item from the queue
    * @param id Item ID
    */
   public async removeItem(id: string): Promise<boolean> {
+    this.assertMutable();
     const item = this.queue.get(id);
     
     if (!item) {
@@ -469,7 +892,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     this.updateStats();
     
     // Emit event
-    this.emit('itemRemoved', item);
+    await emitSafely(this, 'itemRemoved', item);
     logger.log('info', `Item ${id} removed from queue`);
     
     return true;
@@ -489,7 +912,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
 
   private serializeItem(item: IQueueItem): IStoredQueueItem {
     return {
-      schemaVersion: 1,
+      schemaVersion: 2,
       id: item.id,
       processingMode: item.processingMode,
       processingResult: {
@@ -505,6 +928,29 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       createdAt: item.createdAt.getTime(),
       updatedAt: item.updatedAt.getTime(),
       ...(item.deliveredAt ? { deliveredAt: item.deliveredAt.getTime() } : {}),
+      deliveredRecipients: item.deliveredRecipients || [],
+      terminalRecipients: item.terminalRecipients || [],
+      recipientStates: (item.recipientStates || this.createInitialRecipientStates(
+        item.processingResult,
+      )).map((state) => ({
+        ...state,
+        updatedAt: state.updatedAt.getTime(),
+      })),
+      bounceOperations: (item.bounceOperations || []).map((operation) => {
+        const { nextAttempt, completedAt, ...storedOperation } = operation;
+        return {
+          ...storedOperation,
+          nextAttempt: nextAttempt.getTime(),
+          ...(completedAt ? { completedAt: completedAt.getTime() } : {}),
+        };
+      }),
+      smtpTransactions: (item.smtpTransactions || []).slice(-20).map((transaction) => ({
+        ...transaction,
+        queueItemId: item.id,
+        recipients: [...transaction.recipients],
+        recipientResults: transaction.recipientResults?.map((result) => ({ ...result })),
+        transcript: normalizeSmtpTranscript(transaction.transcript),
+      })),
     };
   }
 
@@ -512,7 +958,15 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     item: IQueueItem,
     mutation: (updatedItem: IQueueItem) => void,
   ): Promise<void> {
-    const updatedItem = { ...item };
+    this.assertMutable();
+    const updatedItem: IQueueItem = {
+      ...item,
+      deliveredRecipients: [...(item.deliveredRecipients || [])],
+      terminalRecipients: [...(item.terminalRecipients || [])],
+      recipientStates: (item.recipientStates || []).map((state) => ({ ...state })),
+      bounceOperations: (item.bounceOperations || []).map((operation) => ({ ...operation })),
+      smtpTransactions: [...(item.smtpTransactions || [])],
+    };
     mutation(updatedItem);
     await this.persistItem(updatedItem);
     Object.assign(item, updatedItem);
@@ -527,12 +981,12 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     try {
       parsed = deserialize(data) as Record<string, any>;
     } catch (error) {
-      throw new Error(`Invalid managed queue item at ${key}: ${error.message}`);
+      throw new Error(`Invalid managed queue item at ${key}: ${getErrorMessage(error)}`);
     }
     if (!parsed || typeof parsed !== 'object' || typeof parsed.id !== 'string' || !parsed.id) {
       throw new Error(`Invalid managed queue item at ${key}: missing id`);
     }
-    if (parsed.schemaVersion !== 1) {
+    if (parsed.schemaVersion !== 1 && parsed.schemaVersion !== 2) {
       throw new Error(`Invalid managed queue item at ${key}: unsupported schema version`);
     }
     if (this.storageKey(parsed.id) !== key) {
@@ -548,6 +1002,174 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       throw new Error(`Invalid managed queue item at ${key}: invalid attempt count`);
     }
 
+    if (
+      parsed.deliveredRecipients !== undefined
+      && (
+        !Array.isArray(parsed.deliveredRecipients)
+        || parsed.deliveredRecipients.some((value: unknown) => typeof value !== 'string')
+      )
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid delivered recipients`);
+    }
+    if (
+      parsed.terminalRecipients !== undefined
+      && (
+        !Array.isArray(parsed.terminalRecipients)
+        || parsed.terminalRecipients.some((value: unknown) => typeof value !== 'string')
+      )
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid terminal recipients`);
+    }
+
+    if (parsed.schemaVersion === 2) {
+      if (
+        !Array.isArray(parsed.recipientStates)
+        || parsed.recipientStates.some((value: unknown) => {
+          if (!value || typeof value !== 'object') return true;
+          const state = value as Record<string, unknown>;
+          return !(
+            typeof state.recipient === 'string'
+            && typeof state.normalizedRecipient === 'string'
+            && state.normalizedRecipient === state.recipient.trim().toLowerCase()
+            && ['unresolved', 'delivered', 'permanentFailure'].includes(state.state as string)
+            && Number.isFinite(state.updatedAt)
+            && (state.smtpCode === undefined || Number.isInteger(state.smtpCode))
+            && (state.smtpResponse === undefined || typeof state.smtpResponse === 'string')
+          );
+        })
+      ) {
+        throw new Error(`Invalid managed queue item at ${key}: invalid recipient states`);
+      }
+      if (
+        !Array.isArray(parsed.bounceOperations)
+        || parsed.bounceOperations.some((value: unknown) => {
+          if (!value || typeof value !== 'object') return true;
+          const operation = value as Record<string, unknown>;
+          return !(
+            typeof operation.operationId === 'string'
+            && operation.operationId.length > 0
+            && operation.kind === 'smtpFailure'
+            && typeof operation.recipient === 'string'
+            && typeof operation.normalizedRecipient === 'string'
+            && operation.normalizedRecipient === operation.recipient.trim().toLowerCase()
+            && Number.isInteger(operation.smtpCode)
+            && (operation.smtpCode as number) >= 500
+            && typeof operation.smtpResponse === 'string'
+            && ['pending', 'completed'].includes(operation.state as string)
+            && Number.isInteger(operation.attempts)
+            && (operation.attempts as number) >= 0
+            && Number.isFinite(operation.nextAttempt)
+            && (operation.lastError === undefined || typeof operation.lastError === 'string')
+            && (operation.completedAt === undefined || Number.isFinite(operation.completedAt))
+          );
+        })
+      ) {
+        throw new Error(`Invalid managed queue item at ${key}: invalid bounce operations`);
+      }
+    }
+
+    const deliveryPhases = new Set([
+      'connect',
+      'greeting',
+      'ehlo',
+      'starttls',
+      'tls_handshake',
+      'post_tls_ehlo',
+      'auth',
+      'mail_from',
+      'rcpt_to',
+      'data_command',
+      'message_body',
+      'final_response',
+      'rset',
+      'quit',
+      'unknown',
+    ]);
+    const isValidTimestamp = (value: unknown): value is string => (
+      typeof value === 'string' && Number.isFinite(Date.parse(value))
+    );
+    const isValidTranscriptEntry = (value: unknown): boolean => {
+      if (!value || typeof value !== 'object') return false;
+      const entry = value as Record<string, unknown>;
+      return (
+        typeof entry.timestampMs === 'number'
+        && Number.isFinite(entry.timestampMs)
+        && deliveryPhases.has(entry.phase as string)
+        && ['client', 'server', 'system'].includes(entry.direction as string)
+        && typeof entry.text === 'string'
+        && [...entry.text].length <= SMTP_TRANSCRIPT_MAX_ENTRY_CODE_POINTS
+        && (
+          entry.responseCode === undefined
+          || (Number.isInteger(entry.responseCode) && (entry.responseCode as number) >= 100)
+        )
+      );
+    };
+    const isValidTransaction = (value: unknown): boolean => {
+      if (!value || typeof value !== 'object') return false;
+      const transaction = value as Record<string, unknown>;
+      return (
+        typeof transaction.id === 'string'
+        && transaction.id.length > 0
+        && transaction.queueItemId === parsed.id
+        && Number.isInteger(transaction.queueAttempt)
+        && (transaction.queueAttempt as number) >= 0
+        && typeof transaction.targetHost === 'string'
+        && transaction.targetHost.length > 0
+        && Number.isInteger(transaction.targetPort)
+        && (transaction.targetPort as number) >= 1
+        && (transaction.targetPort as number) <= 65_535
+        && (
+          transaction.recipientDomain === undefined
+          || typeof transaction.recipientDomain === 'string'
+        )
+        && Array.isArray(transaction.recipients)
+        && transaction.recipients.every((recipient) => typeof recipient === 'string')
+        && isValidTimestamp(transaction.startedAt)
+        && isValidTimestamp(transaction.completedAt)
+        && typeof transaction.durationMs === 'number'
+        && Number.isFinite(transaction.durationMs)
+        && transaction.durationMs >= 0
+        && ['succeeded', 'failed'].includes(transaction.outcome as string)
+        && typeof transaction.retryable === 'boolean'
+        && (transaction.errorType === undefined || typeof transaction.errorType === 'string')
+        && (transaction.smtpCode === undefined || Number.isInteger(transaction.smtpCode))
+        && (
+          transaction.recipientResults === undefined
+          || (
+            Array.isArray(transaction.recipientResults)
+            && transaction.recipientResults.every((value) => {
+              if (!value || typeof value !== 'object') return false;
+              const result = value as Record<string, unknown>;
+              return (
+                typeof result.recipient === 'string'
+                && typeof result.accepted === 'boolean'
+                && Number.isInteger(result.responseCode)
+              );
+            })
+          )
+        )
+        && (transaction.failurePhase === undefined || deliveryPhases.has(transaction.failurePhase as string))
+        && (transaction.error === undefined || typeof transaction.error === 'string')
+        && Array.isArray(transaction.transcript)
+        && transaction.transcript.length <= SMTP_TRANSCRIPT_MAX_ENTRIES
+        && transaction.transcript.every(isValidTranscriptEntry)
+        && transaction.transcript.reduce(
+          (sum, entry) => sum + Buffer.byteLength((entry as { text: string }).text, 'utf8'),
+          0,
+        ) <= SMTP_TRANSCRIPT_MAX_UTF8_BYTES
+      );
+    };
+    if (
+      parsed.smtpTransactions !== undefined
+      && (
+        !Array.isArray(parsed.smtpTransactions)
+        || parsed.smtpTransactions.length > 20
+        || parsed.smtpTransactions.some((value: unknown) => !isValidTransaction(value))
+      )
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid SMTP transactions`);
+    }
+
     const parseDate = (value: unknown, field: string): Date => {
       if (!Number.isFinite(value) || (value as number) < 0) {
         throw new Error(`Invalid managed queue item at ${key}: invalid ${field}`);
@@ -585,7 +1207,38 @@ export class UnifiedDeliveryQueue extends EventEmitter {
         .setMessageId(parsed.processingResult.messageId)
         .setEnvelopeFrom(parsed.processingResult.envelopeFrom);
     } catch (error) {
-      throw new Error(`Invalid managed queue item at ${key}: ${error.message}`);
+      throw new Error(`Invalid managed queue item at ${key}: ${getErrorMessage(error)}`);
+    }
+
+    let recipientStates: IRecipientDeliveryState[];
+    let bounceOperations: IBounceOperation[];
+    if (parsed.schemaVersion === 2) {
+      recipientStates = parsed.recipientStates.map((state: IStoredRecipientDeliveryState) => ({
+        ...state,
+        updatedAt: parseDate(state.updatedAt, 'recipient state updatedAt'),
+      }));
+      bounceOperations = parsed.bounceOperations.map((operation: IStoredBounceOperation) => ({
+        ...operation,
+        nextAttempt: parseDate(operation.nextAttempt, 'bounce operation nextAttempt'),
+        ...(operation.completedAt !== undefined
+          ? { completedAt: parseDate(operation.completedAt, 'bounce operation completedAt') }
+          : {}),
+      }));
+    } else {
+      // V1 hydration deliberately starts with an empty outbox. Bounce work is
+      // never synthesized retroactively without a durable recipient transition.
+      recipientStates = this.createInitialRecipientStates(processingResult);
+      const delivered = new Set(
+        (parsed.deliveredRecipients || []).map((recipient: string) => recipient.toLowerCase()),
+      );
+      const terminal = new Set(
+        (parsed.terminalRecipients || []).map((recipient: string) => recipient.toLowerCase()),
+      );
+      for (const state of recipientStates) {
+        if (delivered.has(state.normalizedRecipient)) state.state = 'delivered';
+        else if (terminal.has(state.normalizedRecipient)) state.state = 'permanentFailure';
+      }
+      bounceOperations = [];
     }
 
     return {
@@ -602,6 +1255,22 @@ export class UnifiedDeliveryQueue extends EventEmitter {
       ...(parsed.deliveredAt
         ? { deliveredAt: parseDate(parsed.deliveredAt, 'deliveredAt') }
         : {}),
+      deliveredRecipients: Array.isArray(parsed.deliveredRecipients)
+        ? [...parsed.deliveredRecipients]
+        : [],
+      terminalRecipients: Array.isArray(parsed.terminalRecipients)
+        ? [...parsed.terminalRecipients]
+        : [],
+      recipientStates,
+      bounceOperations,
+      smtpTransactions: Array.isArray(parsed.smtpTransactions)
+        ? parsed.smtpTransactions.slice(-20).map((transaction) => ({
+            ...transaction,
+            recipients: [...transaction.recipients],
+            recipientResults: transaction.recipientResults?.map((result) => ({ ...result })),
+            transcript: normalizeSmtpTranscript(transaction.transcript),
+          }))
+        : [],
     } as IQueueItem;
   }
 
@@ -703,7 +1372,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
     this.stats.processingActive = this.processing;
     
     // Emit statistics event
-    this.emit('statsUpdated', this.stats);
+    void emitSafely(this, 'statsUpdated', this.stats);
   }
   
   /**
@@ -717,6 +1386,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * Pause queue processing
    */
   public pause(): void {
+    this.assertMutable();
     if (this.processing) {
       this.stopProcessing();
       logger.log('info', 'Queue processing paused');
@@ -727,6 +1397,7 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * Resume queue processing
    */
   public resume(): void {
+    this.assertMutable();
     if (!this.processing) {
       this.startProcessing();
       logger.log('info', 'Queue processing resumed');
@@ -738,12 +1409,20 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * @param maxAge Maximum age in milliseconds (default: 7 days)
    */
   public async cleanupOldItems(maxAge: number = 7 * 24 * 60 * 60 * 1000): Promise<number> {
+    this.assertMutable();
     const cutoff = new Date(Date.now() - maxAge);
 
     // Collect IDs first to avoid modifying the Map during iteration
     const idsToRemove: string[] = [];
     for (const item of this.queue.values()) {
-      if (['delivered', 'failed'].includes(item.status) && item.updatedAt < cutoff) {
+      const hasPendingBounceWork = (item.bounceOperations || []).some(
+        (operation) => operation.state !== 'completed',
+      );
+      if (
+        ['delivered', 'failed'].includes(item.status)
+        && item.updatedAt < cutoff
+        && !hasPendingBounceWork
+      ) {
         idsToRemove.push(item.id);
       }
     }
@@ -763,31 +1442,34 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * Shutdown the queue
    */
   public async shutdown(): Promise<void> {
+    if (this.lifecycleState === 'closed') return;
     logger.log('info', 'Shutting down UnifiedDeliveryQueue');
-    
-    // Stop processing (clears both check and cleanup timers)
-    this.stopProcessing();
-    
-    // Persist all items when durable blob storage is configured
-    if (this.options.storageManager) {
-      const pendingWrites: Promise<void>[] = [];
-      
-      for (const item of this.queue.values()) {
-        pendingWrites.push(this.persistItem(item));
+    this.lifecycleState = 'shutting-down';
+    let persistenceError: unknown;
+
+    try {
+      // Stop processing (clears both check and cleanup timers).
+      this.stopProcessing();
+
+      if (this.options.storageManager) {
+        await Promise.all(
+          [...this.queue.values()].map((item) => this.persistItem(item)),
+        );
       }
-      
-      // Wait for all writes to complete
-      await Promise.all(pendingWrites);
+    } catch (error) {
+      // Preserve the original persistence failure; observer diagnostics are
+      // isolated and can never replace it.
+      persistenceError = error;
+      logger.log('error', `Failed to persist delivery queue during shutdown: ${(error as Error).message}`);
+    } finally {
+      this.queue.clear();
+      this.updateStats();
+      await emitSafely(this, 'shutdown');
+      this.lifecycleState = 'closed';
+      this.releaseManagedPrefix();
     }
-    
-    // Clear the queue (memory only)
-    this.queue.clear();
-    
-    // Update statistics
-    this.updateStats();
-    
-    // Emit shutdown event
-    this.emit('shutdown');
+
+    if (persistenceError) throw persistenceError;
     logger.log('info', 'UnifiedDeliveryQueue shut down successfully');
   }
 }