@push.rocks/smartmta 6.5.2 → 8.0.0

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

@@ -1,23 +1,64 @@
-import * as plugins from '../../plugins.js';
 import { EventEmitter } from 'node:events';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
+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
  */
 export interface IQueueItem {
   id: string;
   processingMode: EmailProcessingMode;
-  processingResult: any;
+  processingResult: Email;
   route?: IEmailRoute;
   status: QueueItemStatus;
   attempts: number;
@@ -26,15 +67,77 @@ export interface IQueueItem {
   createdAt: Date;
   updatedAt: Date;
   deliveredAt?: Date;
+  deliveredRecipients?: string[];
+  terminalRecipients?: string[];
+  recipientStates?: IRecipientDeliveryState[];
+  bounceOperations?: IBounceOperation[];
+  smtpTransactions?: ISmtpTransactionAttempt[];
+}
+
+interface IStoredEmail {
+  options: IEmailOptions;
+  messageId: string;
+  envelopeFrom: string;
+}
+
+interface IStoredQueueItemV1 {
+  schemaVersion: 1;
+  id: string;
+  processingMode: EmailProcessingMode;
+  processingResult: IStoredEmail;
+  route?: IEmailRoute;
+  status: QueueItemStatus;
+  attempts: number;
+  nextAttempt: number;
+  lastError?: string;
+  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';
 }
 
 /**
  * Queue options interface
  */
 export interface IQueueOptions {
-  // Storage options
-  storageType?: 'memory' | 'disk';
-  persistentPath?: string;
+  /** Persistence is always an explicit caller choice. */
+  storageMode: 'memory' | 'managed';
+  /** Required when storageMode is managed. */
+  storageManager?: IBlobStorageManager;
+  storagePrefix?: string;
   
   // Queue behavior
   checkInterval?: number;
@@ -50,6 +153,22 @@ export interface IQueueOptions {
 /**
  * Queue statistics interface
  */
+function normalizeStoragePrefix(prefixArg = '/email/queue/'): string {
+  if (
+    !prefixArg.startsWith('/') ||
+    !prefixArg.endsWith('/') ||
+    prefixArg.includes('\\') ||
+    prefixArg.includes('\0')
+  ) {
+    throw new Error('Queue storagePrefix must be an absolute managed-storage prefix');
+  }
+  const segments = prefixArg.slice(1, -1).split('/');
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+    throw new Error('Queue storagePrefix contains an invalid path segment');
+  }
+  return prefixArg;
+}
+
 export interface IQueueStats {
   queueSize: number;
   status: {
@@ -71,17 +190,32 @@ export interface IQueueStats {
   processingActive: boolean;
 }
 
+const managedQueueOwners =
+  new WeakMap<IBlobStorageManager, Map<string, UnifiedDeliveryQueue>>();
+
 /**
  * A unified queue for all email modes
  */
 export class UnifiedDeliveryQueue extends EventEmitter {
-  private options: Required<IQueueOptions>;
+  private options: {
+    storageMode: 'memory' | 'managed';
+    storageManager?: IBlobStorageManager;
+    storagePrefix: string;
+    checkInterval: number;
+    maxQueueSize: number;
+    maxPerDestination: number;
+    maxRetries: number;
+    baseRetryDelay: number;
+    maxRetryDelay: number;
+  };
   private queue: Map<string, IQueueItem> = new Map();
   private checkTimer?: NodeJS.Timeout;
   private cleanupTimer?: NodeJS.Timeout;
   private stats: IQueueStats;
   private processing: boolean = false;
   private totalProcessed: number = 0;
+  private ownsManagedPrefix = false;
+  private lifecycleState: TQueueLifecycleState = 'new';
   
   /**
    * Create a new unified delivery queue
@@ -89,11 +223,18 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    */
   constructor(options: IQueueOptions) {
     super();
-    
-    // Set default options
+
+    if (options.storageMode === 'managed' && !options.storageManager) {
+      throw new Error('Managed queue storage requires an IBlobStorageManager');
+    }
+    if (options.storageMode === 'memory' && options.storageManager) {
+      throw new Error('Memory-only queue storage cannot receive an IBlobStorageManager');
+    }
+
     this.options = {
-      storageType: options.storageType || 'memory',
-      persistentPath: options.persistentPath || path.join(process.cwd(), 'email-queue'),
+      storageMode: options.storageMode,
+      storageManager: options.storageManager,
+      storagePrefix: normalizeStoragePrefix(options.storagePrefix),
       checkInterval: options.checkInterval || 30000, // 30 seconds
       maxQueueSize: options.maxQueueSize || 10000,
       maxPerDestination: options.maxPerDestination || 100,
@@ -122,32 +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 {
-      // Create persistent storage directory if using disk storage
-      if (this.options.storageType === 'disk') {
-        if (!fs.existsSync(this.options.persistentPath)) {
-          fs.mkdirSync(this.options.persistentPath, { recursive: true });
-        }
-        
-        // Load existing items from disk
-        await this.loadFromDisk();
+      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;
     }
   }
@@ -174,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');
   }
   
@@ -193,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');
   }
   
@@ -220,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);
     }
   }
   
@@ -237,7 +444,16 @@ export class UnifiedDeliveryQueue extends EventEmitter {
    * @param mode Processing mode
    * @param route Email route
    */
-  public async enqueue(processingResult: any, mode: EmailProcessingMode, route?: IEmailRoute): Promise<string> {
+  public async enqueue(
+    processingResult: Email,
+    mode: EmailProcessingMode,
+    route?: IEmailRoute,
+  ): Promise<string> {
+    this.assertMutable();
+    if (!(processingResult instanceof Email)) {
+      throw new Error('Queue processingResult must be an Email instance');
+    }
+
     // Check if queue is full
     if (this.queue.size >= this.options.maxQueueSize) {
       throw new Error('Queue is full');
@@ -256,22 +472,23 @@ 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: [],
     };
     
-    // Add to queue
+    // Commit durable state before exposing the item in memory or emitting acceptance.
+    await this.persistItem(item);
     this.queue.set(id, item);
     
-    // Persist to disk if using disk storage
-    if (this.options.storageType === 'disk') {
-      await this.persistItem(item);
-    }
-    
     // Update statistics
     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;
@@ -286,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 })),
+      })),
+    }));
   }
   
   /**
@@ -294,27 +523,30 @@ 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;
     }
     
-    // Update status
-    item.status = 'processing';
-    item.attempts++;
-    item.updatedAt = new Date();
-    
-    // Persist changes if using disk storage
-    if (this.options.storageType === 'disk') {
-      await this.persistItem(item);
-    }
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      updatedItem.status = 'processing';
+      updatedItem.attempts++;
+      updatedItem.updatedAt = new Date();
+    });
     
     // Update statistics
     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;
@@ -325,28 +557,25 @@ 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;
     }
     
-    // Update status
-    item.status = 'delivered';
-    item.updatedAt = new Date();
-    item.deliveredAt = new Date();
-    
-    // Persist changes if using disk storage
-    if (this.options.storageType === 'disk') {
-      await this.persistItem(item);
-    }
+    await this.applyPersistedMutation(item, (updatedItem) => {
+      updatedItem.status = 'delivered';
+      updatedItem.updatedAt = new Date();
+      updatedItem.deliveredAt = new Date();
+    });
     
     // Update statistics
     this.totalProcessed++;
     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;
@@ -357,165 +586,734 @@ 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),
         this.options.maxRetryDelay
       );
       
-      // Update status
-      item.status = 'deferred';
-      item.lastError = error;
-      item.nextAttempt = new Date(Date.now() + delay);
-      item.updatedAt = new Date();
-      
-      // Persist changes if using disk storage
-      if (this.options.storageType === 'disk') {
-        await this.persistItem(item);
-      }
+      await this.applyPersistedMutation(item, (updatedItem) => {
+        updatedItem.status = 'deferred';
+        updatedItem.lastError = error;
+        updatedItem.nextAttempt = new Date(Date.now() + delay);
+        updatedItem.updatedAt = new Date();
+      });
       
       // 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
-      item.status = 'failed';
-      item.lastError = error;
-      item.updatedAt = new Date();
-      
-      // Persist changes if using disk storage
-      if (this.options.storageType === 'disk') {
-        await this.persistItem(item);
-      }
+      await this.applyPersistedMutation(item, (updatedItem) => {
+        updatedItem.status = 'failed';
+        updatedItem.lastError = error;
+        updatedItem.updatedAt = new Date();
+      });
       
       // Update statistics
       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) {
       return false;
     }
     
-    // Remove from queue
+    // Delete durable state before making the removal visible in memory.
+    await this.removeItemFromStorage(id);
     this.queue.delete(id);
     
-    // Remove from disk if using disk storage
-    if (this.options.storageType === 'disk') {
-      await this.removeItemFromDisk(id);
-    }
-    
     // Update statistics
     this.updateStats();
     
     // Emit event
-    this.emit('itemRemoved', item);
+    await emitSafely(this, 'itemRemoved', item);
     logger.log('info', `Item ${id} removed from queue`);
     
     return true;
   }
   
-  /**
-   * Persist an item to disk
-   * @param item Item to persist
-   */
+  private storageKey(id: string): string {
+    return `${this.options.storagePrefix}${id}.json`;
+  }
+
   private async persistItem(item: IQueueItem): Promise<void> {
+    if (!this.options.storageManager) return;
+    await this.options.storageManager.set(
+      this.storageKey(item.id),
+      serialize(this.serializeItem(item)),
+    );
+  }
+
+  private serializeItem(item: IQueueItem): IStoredQueueItem {
+    return {
+      schemaVersion: 2,
+      id: item.id,
+      processingMode: item.processingMode,
+      processingResult: {
+        options: item.processingResult.toEmailOptions(),
+        messageId: item.processingResult.getMessageId(),
+        envelopeFrom: item.processingResult.getEnvelopeFrom(),
+      },
+      ...(item.route ? { route: item.route } : {}),
+      status: item.status,
+      attempts: item.attempts,
+      nextAttempt: item.nextAttempt.getTime(),
+      ...(item.lastError !== undefined ? { lastError: item.lastError } : {}),
+      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),
+      })),
+    };
+  }
+
+  private async applyPersistedMutation(
+    item: IQueueItem,
+    mutation: (updatedItem: IQueueItem) => void,
+  ): Promise<void> {
+    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);
+  }
+
+  private async removeItemFromStorage(id: string): Promise<void> {
+    await this.options.storageManager?.delete(this.storageKey(id));
+  }
+
+  private deserializeItem(key: string, data: Buffer): IQueueItem {
+    let parsed: Record<string, any>;
     try {
-      const filePath = path.join(this.options.persistentPath, `${item.id}.json`);
-      await fs.promises.writeFile(filePath, JSON.stringify(item, null, 2), 'utf8');
+      parsed = deserialize(data) as Record<string, any>;
     } catch (error) {
-      logger.log('error', `Failed to persist item ${item.id}: ${error.message}`);
-      this.emit('error', error);
+      throw new Error(`Invalid managed queue item at ${key}: ${getErrorMessage(error)}`);
     }
-  }
-  
-  /**
-   * Remove an item from disk
-   * @param id Item ID
-   */
-  private async removeItemFromDisk(id: string): Promise<void> {
-    try {
-      const filePath = path.join(this.options.persistentPath, `${id}.json`);
-      
-      if (fs.existsSync(filePath)) {
-        await fs.promises.unlink(filePath);
+    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 && parsed.schemaVersion !== 2) {
+      throw new Error(`Invalid managed queue item at ${key}: unsupported schema version`);
+    }
+    if (this.storageKey(parsed.id) !== key) {
+      throw new Error(`Invalid managed queue item at ${key}: id does not match object key`);
+    }
+    if (!['pending', 'processing', 'delivered', 'failed', 'deferred'].includes(parsed.status)) {
+      throw new Error(`Invalid managed queue item at ${key}: unsupported status`);
+    }
+    if (!['forward', 'mta', 'process'].includes(parsed.processingMode)) {
+      throw new Error(`Invalid managed queue item at ${key}: unsupported processing mode`);
+    }
+    if (!Number.isInteger(parsed.attempts) || parsed.attempts < 0) {
+      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`);
       }
-    } catch (error) {
-      logger.log('error', `Failed to remove item ${id} from disk: ${error.message}`);
-      this.emit('error', error);
     }
-  }
-  
-  /**
-   * Load queue items from disk
-   */
-  private async loadFromDisk(): Promise<void> {
-    try {
-      // Check if directory exists
-      if (!fs.existsSync(this.options.persistentPath)) {
-        return;
+
+    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}`);
       }
-      
-      // Get all JSON files
-      const files = fs.readdirSync(this.options.persistentPath).filter(file => file.endsWith('.json'));
-      
-      // Load each file
-      for (const file of files) {
-        try {
-          const filePath = path.join(this.options.persistentPath, file);
-          const data = await fs.promises.readFile(filePath, 'utf8');
-          const item = JSON.parse(data) as IQueueItem;
-          
-          // Convert date strings to Date objects
-          item.createdAt = new Date(item.createdAt);
-          item.updatedAt = new Date(item.updatedAt);
-          item.nextAttempt = new Date(item.nextAttempt);
-          if (item.deliveredAt) {
-            item.deliveredAt = new Date(item.deliveredAt);
-          }
-          
-          // Add to queue
-          this.queue.set(item.id, item);
-        } catch (error) {
-          logger.log('error', `Failed to load item from ${file}: ${error.message}`);
+      return new Date(value as number);
+    };
+
+    if (
+      !parsed.processingResult ||
+      typeof parsed.processingResult !== 'object' ||
+      !parsed.processingResult.options ||
+      typeof parsed.processingResult.options !== 'object' ||
+      typeof parsed.processingResult.messageId !== 'string' ||
+      !parsed.processingResult.messageId ||
+      typeof parsed.processingResult.envelopeFrom !== 'string'
+    ) {
+      throw new Error(`Invalid managed queue item at ${key}: invalid email payload`);
+    }
+
+    const storedOptions = parsed.processingResult.options as IEmailOptions;
+    if (storedOptions.attachments !== undefined) {
+      if (!Array.isArray(storedOptions.attachments)) {
+        throw new Error(`Invalid managed queue item at ${key}: invalid attachments`);
+      }
+      for (const attachment of storedOptions.attachments) {
+        if (!attachment || typeof attachment !== 'object' || !Buffer.isBuffer(attachment.content)) {
+          throw new Error(`Invalid managed queue item at ${key}: invalid attachment content`);
         }
       }
-      
-      // Update statistics
-      this.updateStats();
-      
-      logger.log('info', `Loaded ${this.queue.size} items from disk`);
+    }
+
+    let processingResult: Email;
+    try {
+      processingResult = new Email(storedOptions)
+        .setMessageId(parsed.processingResult.messageId)
+        .setEnvelopeFrom(parsed.processingResult.envelopeFrom);
     } catch (error) {
-      logger.log('error', `Failed to load items from disk: ${error.message}`);
-      throw error;
+      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 {
+      id: parsed.id,
+      processingMode: parsed.processingMode,
+      processingResult,
+      ...(parsed.route ? { route: parsed.route as IEmailRoute } : {}),
+      status: parsed.status,
+      attempts: parsed.attempts,
+      ...(typeof parsed.lastError === 'string' ? { lastError: parsed.lastError } : {}),
+      createdAt: parseDate(parsed.createdAt, 'createdAt'),
+      updatedAt: parseDate(parsed.updatedAt, 'updatedAt'),
+      nextAttempt: parseDate(parsed.nextAttempt, 'nextAttempt'),
+      ...(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;
+  }
+
+  private async loadFromStorage(): Promise<void> {
+    const storageManager = this.options.storageManager;
+    if (!storageManager) return;
+    const keys = (await storageManager.list(this.options.storagePrefix)).sort();
+    const recoveredItems: IQueueItem[] = [];
+
+    for (const key of keys) {
+      if (!key.startsWith(this.options.storagePrefix)) {
+        throw new Error(`Blob storage returned a queue key outside ${this.options.storagePrefix}: ${key}`);
+      }
+      if (!key.endsWith('.json')) continue;
+      const data = await storageManager.get(key);
+      if (!data) {
+        throw new Error(`Managed queue item disappeared while loading: ${key}`);
+      }
+      const item = this.deserializeItem(key, data);
+      if (this.queue.has(item.id)) {
+        throw new Error(`Duplicate managed queue item id: ${item.id}`);
+      }
+      if (this.queue.size >= this.options.maxQueueSize) {
+        throw new Error(`Managed queue contains more than ${this.options.maxQueueSize} items`);
+      }
+      if (item.status === 'processing') {
+        item.status = 'deferred';
+        item.nextAttempt = new Date();
+        item.updatedAt = new Date();
+        item.lastError = 'Recovered after process restart during delivery';
+        recoveredItems.push(item);
+      }
+      this.queue.set(item.id, item);
     }
+
+    await Promise.all(recoveredItems.map((item) => this.persistItem(item)));
+    this.updateStats();
+    logger.log(
+      'info',
+      `Loaded ${this.queue.size} items from managed blob storage; recovered ${recoveredItems.length} interrupted item(s)`,
+    );
   }
-  
+
   /**
    * Update queue statistics
    */
@@ -574,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);
   }
   
   /**
@@ -588,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');
@@ -598,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');
@@ -609,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);
       }
     }
@@ -634,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();
-    
-    // If using disk storage, make sure all items are persisted
-    if (this.options.storageType === 'disk') {
-      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');
   }
 }