Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

83.3 KB
Raw Blame
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { Injectable, Optional } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository, In, Not } from 'typeorm';
import { QueryDeepPartialEntity } from 'typeorm';
import { Session } from './entities/session.entity';
import { Message, MessageDirection, MessageStatus } from '../message/entities/message.entity';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { KeyedMutationQueue } from '../../common/utils/keyed-mutation-queue';
import { awaitNoOpenTransaction } from '../../common/utils/shared-connection';
import { captureSessionWrites } from '../../common/utils/session-write-scope';
import { SessionLidResolver } from './session-lid-resolver.service';
import { buildMessageMetadata, REVOKED_ROW_PATCH, storableWaMessageId } from './message-row.mapper';
import { MessageMutationProjector } from './message-mutation-projector';
import {
  mutationTargetsForeignRow,
  mutationTargetsForeignRowPersisted,
  type MutationSource,
  type StoredMessageRef,
} from './message-mutation-guard';
import { updateMessageMetadata } from '../message/message-metadata';
import { persistHistoryMessages } from './message-history-projector';
import { isTransientDbError, isUniqueViolation } from '../../common/utils/db-errors';
import { resolveFeatureFlags } from '../../config/feature-flags';
import { StatusStoreService } from '../status-store/status-store.service';
import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.service';
import { AutomationRulesService } from '../automation/automation-rules.service';
import { buildIncomingStatus } from '../status-store/incoming-status';
import type { StatusUpdate } from '../status-store/entities/status-update.entity';
import {
  IWhatsAppEngine,
  DeliveryStatus,
  MessageReceiptEvent,
  IncomingMessage,
  InboundOutcome,
  InboundReceipt,
  InboundTicket,
  ReactionEvent,
  EditedMessage,
  RevokedMessage,
} from '../../engine/interfaces/whatsapp-engine.interface';
import { deferred, InboundRoom, roomState, type RoomState } from './inbound-room';
import { createLogger } from '../../common/services/logger.service';
import { EventsGateway } from '../events/events.gateway';
import { WebhookService } from '../webhook/webhook.service';
import { HookManager } from '../../core/hooks';
import {
  deliveryStatusToMessageStatus,
  deliveryStatusToAck,
  ackStatusTransitionFrom,
} from '../message/message-status.util';
import { isMessagePayload } from '../../core/hooks/hook-results';

/**
 * Projects engine message events into the `messages` table and out to webhooks/WebSocket.
 *
 * This is the data path for messages: inbound arrivals, own-send echoes, delivery acks, revokes,
 * reactions, edits, and the pre-connection history backfill. It is deliberately separate from
 * SessionEngineLifecycle, which owns the session *lifecycle* (start/stop/delete/reconnect). The two
 * share
 * only the engine identity guard — a late event from a superseded engine must never mutate a
 * session that now belongs to a different one, or to none — which both read from EngineRegistry.
 *
 * Every entry point takes the captured `(sessionId, engine)` pair its engine callback closed over,
 * so those staleness checks behave exactly as they did while this code sat inline in
 * initializeEngine.
 */
/**
 * Delay before retrying an ack UPDATE that matched 0 rows. A fast delivered/read ack can arrive before
 * the send's 2nd save (which writes waMessageId) has committed, so the first UPDATE finds no row. One
 * retry after this delay closes that race; the forward-only transition guard keeps it idempotent.
 */
export const ACK_RECONCILE_DELAY_MS = 750;

/**
 * Delay before the single retry of a message insert that failed transiently (lock contention, a
 * dropped connection, a pool timeout). The engine delivers each message once, so without the retry
 * one busy moment loses the row for good.
 */
export const PERSIST_RETRY_DELAY_MS = 300;

/** How many of its messages marked edited a session remembers as marked (see markedEdited). */
const EDITED_MARKS_KEPT_PER_SESSION = 500;

/**
 * How a message insert ended: `yes` the row landed, `dup` a unique violation (`retried` says whether
 * it came from the retry, when the first attempt may have committed before its error), `failed` a
 * non-conflict error, `stale` the engine was retired while the retry waited.
 */
type InsertOutcome = { landed: 'yes' | 'failed' | 'stale' } | { landed: 'dup'; retried: boolean };

/** Persist-stage outcome threaded into the inbound dispatch stage (was closure state in the hook continuation). */
interface InboundPersistOutcome {
  dbMessage: Message;
  persisted: boolean;
}

/**
 * Type of the `{ ...message }` copy the `message:received` hook returns (was the closure-inferred
 * spread type in handleInboundMessage). Kept as an object type rather than the IncomingMessage
 * interface so it stays assignable to the Record<string, unknown> dispatch/emit params — interfaces
 * carry no implicit index signature.
 */
type InboundMessageData = { [K in keyof IncomingMessage]: IncomingMessage[K] };

const quoteOf = (m: Pick<IncomingMessage, 'chatId' | 'body'>) => ({ chatId: m.chatId, body: m.body });

/** A deleted message as hooks and consumers see it: nothing of its content survives, as in REVOKED_ROW_PATCH. */
const deletedPlaceholder = (message: InboundMessageData): InboundMessageData => {
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  const { media, quotedMessage, call, buttons, button, location, order, product, poll, mentionedIds, ...kept } =
    message;
  return { ...kept, body: '', type: 'revoked' };
};

/** Where a message lives and who wrote it: what a change aimed at it is held to (see mutationTargetsForeignRow). */
const refOf = (m: Pick<IncomingMessage, 'chatId' | 'fromMe' | 'author'>): StoredMessageRef => ({
  chatId: m.chatId,
  direction: m.fromMe ? MessageDirection.OUTGOING : MessageDirection.INCOMING,
  author: m.author,
});

/** What a delivery claims to be, as the rule that refuses a change aimed at a stored row reads it. */
const claimOf = (m: Pick<IncomingMessage, 'chatId' | 'fromMe' | 'author'>): MutationSource => ({
  kind: 'edit',
  chatId: m.chatId,
  fromMe: m.fromMe,
  author: m.author,
});

/** A message not yet written, and the changes that reached it meanwhile (see inboundInFlight). */
interface InFlightEntry {
  // What a quote of it may lend, as the hook chain last left it. Never the message itself: a repeat
  // delivery shares the entry, and its payload must not outlive the slot that accounts for it.
  // Unset while the message is admitted but not yet emitted (see admitInbound).
  quote?: Pick<IncomingMessage, 'chatId' | 'body'>;
  // Only the active delivery that supplied the checked quote may replace or clear it.
  quoteOwner?: object;
  // Where the message lives and who wrote it, so a change recorded for it meanwhile is held to the same
  // chat, direction and author rule as the row it will become (see mutationTargetsForeignRow).
  ref?: StoredMessageRef;
  revoked?: boolean;
  // Set when the revoke came from the engine, so message.revoked went out for it.
  revokeAnnounced?: boolean;
  editedBody?: string;
  // The text the message arrived with, which an edit is compared with: one that repeats the text so far changes
  // nothing. Unset while the message is admitted but not yet emitted.
  body?: string;
  // An edit held for the message or applied by the engine changed its text, or was asked for: the row it lands on is
  // marked edited.
  edited?: boolean;
  ackStatus?: MessageStatus;
  // Latest reaction per sender; '' means the sender withdrew theirs.
  reactions?: Record<string, string>;
  // Deliveries sharing the entry: a repeat keeps what was recorded for the first one.
  holders?: number;
  // Shared by repeat deliveries while an identity comparison waits for the directory.
  changes?: { pending?: Promise<void> };
}

/** Scalar arrival data and the changes this delivery's identity may inherit. */
interface InFlightDelivery {
  entry: InFlightEntry;
  body: string;
  edited: boolean;
}

/**
 * A message admitted on arrival (PostgreSQL only): its place in the chat's hook and commit order, its
 * claim on the session's room when it downloads media, and its in-flight entry, so a change that
 * targets it before its emit is kept for its row.
 */
class InboundTurn implements InboundTicket {
  state: 'pending' | 'emitted' | 'dropped' = 'pending';
  /** The commit to run in the chat's turn, or null when the message will not be emitted. */
  readonly outcome = deferred<(() => Promise<void>) | null>();
  readonly emitted = deferred<void>();
  /** Resolved once every earlier message of the chat was emitted or dropped: the hook may start. */
  readonly hookGate = deferred<void>();
  private preparing?: Promise<void>;

  constructor(
    readonly engine: IWhatsAppEngine,
    public entry: InFlightEntry,
    private readonly room?: InboundRoom,
    readonly s?: RoomState,
  ) {}

  get revoked(): boolean {
    return this.entry.revoked === true;
  }

  /** A cross-form repeat inherits changes only once its directory comparison has finished. */
  prepareIdentity(pending: Promise<void>): void {
    this.preparing = Promise.race([pending, this.outcome.promise.then(() => undefined)]);
  }

  // A message revoked before its download needs none: its row is stored cleared.
  reserve(): boolean | Promise<boolean> {
    if (!this.s || !this.room || this.state === 'dropped') return false;
    if (this.preparing) {
      const preparing = this.preparing;
      return preparing.then(() => {
        if (this.preparing === preparing) this.preparing = undefined;
        return this.reserve();
      });
    }
    if (this.entry.revoked) return this.giveUp();
    return this.s.granted || this.room.wait(this.s).then(granted => granted && !this.entry.revoked);
  }

  /** Leave the room's queue, if still in it: once admitted, the claim passes the slot straight on. */
  giveUp(): false {
    if (this.s && !this.s.granted) {
      this.s.abandoned = true;
      this.s.grant.resolve(false);
    }
    return false;
  }

  holdUntil(p: Promise<unknown>): void {
    this.s?.holds.push(p.catch(() => undefined));
  }

  emit(job: () => Promise<void>): void {
    if (this.state !== 'pending') return;
    this.state = 'emitted';
    this.emitted.resolve();
    this.outcome.resolve(job);
  }

  drop(): void {
    if (this.state !== 'pending') return;
    this.state = 'dropped';
    this.outcome.resolve(null);
    this.emitted.resolve();
    this.giveUp();
  }
}

@Injectable()
export class MessageProjector {
  private readonly logger = createLogger('MessageProjector');

  // Serializes stored-message mutations per `${sessionId}:${waMessageId}`. Reactions perform a
  // read-modify-write and rapid edits must remain latest-write-wins; sharing one chain also preserves
  // order when different mutation kinds for the same message arrive together.
  private readonly messageMutations = new KeyedMutationQueue((key, err) => {
    // Both current mutation implementations contain their own contextual error handling. Keep a
    // final guard here so a future implementation cannot leak a rejected fire-and-forget promise
    // or permanently block the message's later mutations.
    this.logger.error(`Unexpected failure applying message mutation: ${key}`, String(err));
  });

  // Serializes the insert and dispatch of each chat's messages, by `${sessionId}:${chatId}`: hook
  // chains finish in any order, but a chat's rows, websocket events and webhooks follow arrival.
  private readonly chatCommits = new KeyedMutationQueue((key, err) => {
    this.logger.error(`Unexpected failure committing a message: ${key}`, String(err));
  });

  // PostgreSQL only: a chat's `message:received` / `message:sent` chains start in arrival order, each
  // once every earlier admitted message of the chat was emitted or dropped (see admitInbound).
  private readonly chatEmits = new KeyedMutationQueue((key, err) => {
    this.logger.error(`Unexpected failure ordering a message: ${key}`, String(err));
  });

  // Per session, not per engine: a replaced engine's payloads still waiting for their rows keep
  // counting, so a reconnect cannot multiply the room.
  private readonly rooms = new Map<string, InboundRoom>();

  // Admitted messages not yet committed, by session, so retiring an engine can release its own.
  private readonly tickets = new Map<string, Set<InboundTurn>>();

  // Messages not yet written, by `${sessionId}:${waMessageId}`: inbound ones from the start of their
  // `message:received` chain, own-send echoes from the start of their `message:sent` chain, each until
  // its commit (which may wait behind earlier messages of the chat) ends. A handler that quotes the
  // message reads it from here, and a revoke, edit or ack landing meanwhile finds no row to update: it
  // is recorded here and applied once the row is written (see applyChangesMadeInFlight).
  // On PostgreSQL the entry exists from the message's arrival (admitInbound), before its emit.
  private readonly inboundInFlight = new Map<string, InFlightEntry>();

  // Ids whose row was marked edited, by session, while it has an engine: an own message delivered again loses its
  // insert to that row, and is announced with the mark without reading it (see commitOwnSendEcho). Never stored; past
  // EDITED_MARKS_KEPT_PER_SESSION the oldest is forgotten, and a repeat of it goes out unmarked.
  private readonly markedEdited = new Map<string, Set<string>>();

  // Reaction/edit applies, extracted to a plain collaborator. It shares this instance's
  // messageMutations queue, so the public enqueue path and the queued applies serialize on one chain.
  private readonly mutationProjector: MessageMutationProjector;

  constructor(
    @InjectRepository(Message, 'data')
    private readonly messageRepository: Repository<Message>,
    @InjectRepository(Session, 'data')
    private readonly sessionRepository: Repository<Session>,
    private readonly engines: EngineRegistry,
    private readonly eventsGateway: EventsGateway,
    private readonly webhookService: WebhookService,
    private readonly hookManager: HookManager,
    private readonly statusStore: StatusStoreService,
    private readonly lidResolver: SessionLidResolver,
    @Optional()
    private readonly configService?: ConfigService,
    // Optional so the projector can still be constructed standalone (specs, and any wiring that
    // predates the archive). Absent simply means inbound media is not archived.
    @Optional()
    private readonly chatMediaArchive?: ChatMediaArchiveService,
    // Optional for the same reason. Absent simply means no autoreply rules are evaluated.
    @Optional()
    private readonly automationRules?: AutomationRulesService,
    @Optional() private readonly lidMappingStore?: LidMappingStoreService,
  ) {
    this.mutationProjector = new MessageMutationProjector(
      this.messageRepository,
      this.eventsGateway,
      this.webhookService,
      this.messageMutations,
      this.logger,
      (sessionId, waMessageId) => this.noteMarkedEdited(sessionId, waMessageId),
      this.lidMappingStore ? jid => this.lidMappingStore!.findPhoneForLid(jid) : undefined,
    );
    this.engines.onRetire((id, engine) => {
      for (const t of this.tickets.get(id) ?? []) if (t.engine === engine) t.drop();
      this.deleteRoomIfIdle(id);
      if (!this.engines.has(id)) this.markedEdited.delete(id);
    });
  }

  private noteMarkedEdited(sessionId: string, waMessageId: string): void {
    let marks = this.markedEdited.get(sessionId);
    if (!marks) this.markedEdited.set(sessionId, (marks = new Set()));
    marks.add(waMessageId);
    if (marks.size > EDITED_MARKS_KEPT_PER_SESSION) marks.delete(marks.values().next().value!);
  }

  /**
   * Whether the engines hold each inbound message from its arrival until its row is written. Only
   * PostgreSQL needs it: a downloaded payload waits in memory for its asynchronous insert, while
   * better-sqlite3 writes synchronously, so the backlog drains within the arrival's own task.
   */
  get holdsInbound(): boolean {
    return this.messageRepository.manager?.connection?.options?.type === 'postgres';
  }

  /**
   * Admit a message as it arrives (see EngineEventCallbacks.admitInbound), synchronously, in arrival
   * order. The engine passes the ticket to its emit or drops it. Each admitted message of a chat
   * starts its hook chain and is committed in this order, and changes that target it before its emit
   * are recorded on its in-flight entry. One that downloads media asks the session's room for a slot
   * now, granted in arrival order and held until its row is written.
   */
  admitInbound(
    id: string,
    engine: IWhatsAppEngine,
    a: { id: string; chatId: string; needsRoom: boolean; status: boolean; fromMe?: boolean; author?: string },
  ): InboundTicket | undefined {
    if (!this.engines.isLive(id, engine)) return undefined;
    const key = a.status || !a.id ? null : `${id}:${a.id}`;
    let entry: InFlightEntry = {};
    if (key) {
      entry = this.inboundInFlight.get(key) ?? entry;
      this.inboundInFlight.set(key, entry);
      // From the arrival, so a change that reaches the message while it downloads media is held to the rule
      // of the row it will become. Only when the engine says whose message it is: a guessed direction
      // would refuse the account's own change.
      if (a.fromMe !== undefined) entry.ref ??= refOf({ chatId: a.chatId, fromMe: a.fromMe, author: a.author });
    }
    entry.holders = (entry.holders ?? 0) + 1;
    const room = a.needsRoom ? this.room(id) : undefined;
    const source: MutationSource = { kind: 'edit', chatId: a.chatId, fromMe: a.fromMe, author: a.author };
    const separate = entry.ref && mutationTargetsForeignRow(entry.ref, source) !== null;
    const scoped: InFlightEntry = separate
      ? { ref: a.fromMe === undefined ? undefined : refOf({ chatId: a.chatId, fromMe: a.fromMe, author: a.author }) }
      : entry;
    const t = new InboundTurn(engine, scoped, room, room && roomState());
    let set = this.tickets.get(id);
    if (!set) this.tickets.set(id, (set = new Set()));
    set.add(t);
    const finish = (): void => {
      if (entry.holders) entry.holders--;
      if (key && !entry.holders && this.inboundInFlight.get(key) === entry) this.inboundInFlight.delete(key);
      set.delete(t);
      if (!set.size && this.tickets.get(id) === set) this.tickets.delete(id);
      t.s?.done.resolve();
    };
    if (a.status) {
      void t.outcome.promise.then(finish);
    } else {
      const chatKey = `${id}:${a.chatId}`;
      this.chatEmits.enqueue(chatKey, () => {
        t.hookGate.resolve();
        return t.emitted.promise;
      });
      this.chatCommits.enqueue(chatKey, async () => {
        try {
          const job = await t.outcome.promise;
          if (job) await job();
        } finally {
          finish();
        }
      });
    }
    if (room && t.s) {
      void room.request(t.s).then(() => {
        if (!this.engines.has(id)) this.deleteRoomIfIdle(id);
      });
    }
    if (key && separate && this.lidMappingStore) {
      const pending = this.changeInFlight(id, a.id, source, (needsRow, shared) => {
        if (!this.engines.isLive(id, engine) || t.state === 'dropped') return;
        if (shared && !needsRow) {
          t.entry = shared;
          if (shared.revoked) t.giveUp();
        }
      });
      // A revoke queued during the directory read must reach the ticket before its download starts.
      if (pending) t.prepareIdentity(pending.then(() => this.waitForInFlightChanges(id, a.id)));
    }
    return t;
  }

  private room(id: string): InboundRoom {
    let room = this.rooms.get(id);
    if (!room) this.rooms.set(id, (room = new InboundRoom()));
    return room;
  }

  private deleteRoomIfIdle(id: string): void {
    if (this.rooms.get(id)?.idle) this.rooms.delete(id);
  }

  /**
   * Engine callback body, lifted out of initializeEngine so the wiring table stays readable. With a
   * ticket (PostgreSQL), the hook chain starts in the chat's arrival order and the commit takes the
   * turn admitInbound reserved; whatever path returns early drops the ticket. The receipt, for an
   * engine that wants to know what became of its message, settles once the commit ends (see
   * {@link InboundOutcome}). There is none when the engine is no longer live or the message is skipped as
   * ephemeral; one that settles with nothing says nothing, as when the hook chain failed.
   */
  handleInboundMessage(
    id: string,
    engine: IWhatsAppEngine,
    message: IncomingMessage,
    ticket?: InboundTicket,
  ): InboundReceipt | undefined {
    const turn = ticket instanceof InboundTurn ? ticket : undefined;
    try {
      return this.receiveInbound(id, engine, message, turn);
    } finally {
      turn?.drop();
    }
  }

  private receiveInbound(
    id: string,
    engine: IWhatsAppEngine,
    message: IncomingMessage,
    turn?: InboundTurn,
  ): InboundReceipt | undefined {
    if (!this.engines.isLive(id, engine)) return;
    if (message.isStatusBroadcast) {
      const ingest = this.ingestInboundStatus(id, engine, message);
      // The status store holds the payload until the ingest settles.
      turn?.holdUntil(ingest);
      // Its own table takes the status whatever the id, and a story is never a row of `messages`: one
      // that finds a message there under its id reuses that id. Only an engine that keeps its own copy of
      // a message reads the outcome, so the lookup is made when it is asked for, and once.
      let judged: Promise<InboundOutcome | undefined> | undefined;
      const judge = (): Promise<InboundOutcome | undefined> => ingest.then(() => this.judgeRepeat(id, message));
      return {
        get settled(): Promise<InboundOutcome | undefined> {
          return (judged ??= judge());
        },
      };
    }
    if (this.shouldSkipEphemeralMessage(id, message)) return;
    this.logger.debug(`Message received from ${message.from}`, {
      sessionId: id,
      messageId: message.id,
      from: message.from,
      action: 'message_received',
    });
    // Update last active timestamp
    void this.sessionRepository.update(id, { lastActiveAt: new Date() }).catch(() => undefined);
    // Convert IncomingMessage to plain object for dispatch. One delivered deleted reaches the hooks with no content,
    // whatever text the engine handed over with it.
    const messageData = message.type === 'revoked' ? deletedPlaceholder(message) : { ...message };
    // What an engine says of the edit it applied is for the session alone: no hook, row or consumer sees it.
    delete messageData.originalBody;
    // Tracks what the chain's current copy lends a quote, so one taken mid-chain carries an earlier
    // handler's rewrite.
    const inFlightKey = `${id}:${message.id}`;
    const inFlight = turn
      ? Object.assign(turn.entry, { ref: turn.entry.ref ?? refOf(messageData) })
      : this.trackInFlight(inFlightKey, messageData);
    const delivery = {
      entry: inFlight,
      body: message.originalBody ?? message.body,
      edited: message.originalBody !== undefined,
    };
    const quoteOwner = {};

    const onFailure = (err: unknown): null => {
      this.logger.error(`onMessage handler failed for ${id}`, String(err));
      return null;
    };
    // Execute hook for message received - plugins can modify or stop processing. The hook chain and
    // sender resolution run concurrently across messages; the catch is attached now so a failure
    // while the commit waits its turn is never an unhandled rejection.
    const prepared = this.startHookChain(id, engine, turn, messageData, delivery, quoteOwner, messageData =>
      this.hookManager
        .execute('message:received', messageData, {
          sessionId: id,
          source: 'Engine',
          accept: data => {
            if (!isMessagePayload(data)) return false;
            if (delivery.entry.quoteOwner === quoteOwner) delivery.entry.quote = quoteOf(data);
            return true;
          },
        })
        .then(({ data }) =>
          this.prepareInboundMessage(id, this.messageOrEngineCopy(id, 'message:received', data, messageData)),
        ),
    ).catch(onFailure);
    const outcome = deferred<InboundOutcome | undefined>();
    this.commitInTurn(id, message, turn, async () => {
      try {
        const finalMessage = await prepared;
        if (finalMessage) outcome.resolve(await this.commitInboundMessage(id, engine, finalMessage, delivery.entry));
      } catch (err) {
        onFailure(err);
      } finally {
        outcome.resolve(undefined); // no effect once settled above
        this.clearQuote(delivery.entry, quoteOwner);
        if (!turn) this.untrackInFlight(inFlightKey, inFlight);
      }
    });
    return { settled: outcome.promise };
  }

  /**
   * Start a message's hook chain: at once without a turn. With one, once every earlier admitted
   * message of the chat was emitted or dropped, so hooks start in arrival order. A message revoked
   * before then skips its hooks, as its content is gone, and an edit made before then reaches them.
   * A delivery of content checks for a stored tombstone before either hook; one that came deleted
   * reaches them cleared. An unavailable database keeps the delivery, as the storage path does.
   */
  private startHookChain(
    id: string,
    engine: IWhatsAppEngine,
    turn: InboundTurn | undefined,
    messageData: InboundMessageData,
    delivery: InFlightDelivery,
    quoteOwner: object,
    run: (message: InboundMessageData) => Promise<InboundMessageData>,
  ): Promise<InboundMessageData | null> {
    const checked = async (): Promise<InboundMessageData | null> => {
      let data = messageData;
      if (data.id && data.type !== 'revoked') {
        try {
          const connection = this.messageRepository.manager?.connection;
          if (connection && !(await awaitNoOpenTransaction(connection))) {
            throw new Error('Timed out waiting for the message database transaction');
          }
          // The unique message key bounds this read. A tombstone outlives this projector and any engine copy.
          const row = await this.messageRepository.findOne({
            where: { sessionId: id, waMessageId: data.id, type: 'revoked' },
            select: { type: true, chatId: true, direction: true, author: true },
          });
          if (
            row?.type === 'revoked' &&
            !(await mutationTargetsForeignRowPersisted(
              row,
              claimOf(data),
              this.lidMappingStore ? jid => this.lidMappingStore!.findPhoneForLid(jid) : undefined,
            ))
          ) {
            data = deletedPlaceholder(data);
          }
        } catch (error) {
          // Preserve the receive path's fail-open behavior when storage is unavailable.
          this.logger.warn('Failed to read the stored message before its hooks; keeping the delivery', {
            sessionId: id,
            messageId: data.id,
            error: String(error),
          });
        }
      }
      if (!this.engines.isLive(id, engine)) return null;
      let result: Promise<InboundMessageData> | null = null;
      const preparing = this.changeInFlight(id, data.id, claimOf(data), (needsRow, pending) => {
        if (!this.engines.isLive(id, engine)) return;
        // A reused id from another identity keeps its own scalar changes, never the first delivery's.
        delivery.entry = pending && !needsRow ? pending : { ref: refOf(data) };
        this.arrive(delivery.entry, delivery);
        const skipHooks = turn && delivery.entry.revoked && messageData.type !== 'revoked';
        if (data.type === 'revoked') this.holdRevoked(id, delivery.entry);
        if (pending && !needsRow) {
          if (pending.revoked) data = deletedPlaceholder(data);
          else if (pending.editedBody !== undefined) data.body = pending.editedBody;
          if (skipHooks) {
            result = Promise.resolve(data);
            return;
          }
          pending.quote = quoteOf(data);
          pending.quoteOwner = quoteOwner;
        }
        // Start the hook in this preparation turn, but never make preparation wait for the hook.
        result = run(data);
      });
      if (preparing) await preparing;
      return result;
    };
    if (!turn) return checked();
    return turn.hookGate.promise.then(async () => {
      await this.waitForInFlightChanges(id, messageData.id);
      if (!this.engines.isLive(id, engine)) return null;
      return checked();
    });
  }

  /** Queue a message's commit on its chat, or hand it to the turn admitInbound already queued. */
  private commitInTurn(
    id: string,
    message: IncomingMessage,
    turn: InboundTurn | undefined,
    job: () => Promise<void>,
  ): void {
    if (turn) turn.emit(job);
    else this.chatCommits.enqueue(this.chatCommitKey(id, message), job);
  }

  /** Record a message as not yet written; a re-fire of the same id keeps the changes recorded so far. */
  private trackInFlight(key: string, message: InboundMessageData): InFlightEntry {
    // A message whose id the engine could not read is registered under no key: the empty id would be shared by
    // every such message, and a revoke or ack that names no message would reach all of them.
    if (!message.id) return { ref: refOf(message) };
    const inFlight = this.inboundInFlight.get(key) ?? {
      // The first delivery of an id says whose message it is: a repeat sent from another chat must not
      // take that over from it, or a change aimed through the repeat would be judged by the wrong rule.
      ref: refOf(message),
    };
    // Repeats can commit through different chat spellings, so none may forget the others' changes.
    // A new entry lends no unchecked quote; a repeat keeps only the previous checked quote.
    inFlight.holders = (inFlight.holders ?? 0) + 1;
    this.inboundInFlight.set(key, inFlight);
    return inFlight;
  }

  /**
   * The engine handed the message over: an edit held until now is compared with the text it arrived with. One the
   * engine applied itself changed that text, though a later one may have restored it (it names the arrival text only
   * then, so it can equal the body), and marks the row the same way.
   */
  private arrive(entry: InFlightEntry, arrival: Pick<InFlightDelivery, 'body' | 'edited'>): void {
    entry.body = arrival.body;
    if (arrival.edited || (entry.editedBody !== undefined && entry.editedBody !== entry.body)) {
      entry.edited = true;
    }
  }

  /** Keep an edit for the row of a message not written yet. One that repeats the text so far changes nothing. */
  private holdEdit(entry: InFlightEntry, body: string): void {
    const soFar = entry.editedBody ?? entry.body;
    if (soFar !== undefined && body !== soFar) entry.edited = true;
    entry.editedBody = body;
  }

  /** Drop the entry once every delivery sharing it has committed. */
  private untrackInFlight(key: string, inFlight: InFlightEntry): void {
    if (inFlight.holders) inFlight.holders--;
    if (!inFlight.holders && this.inboundInFlight.get(key) === inFlight) this.inboundInFlight.delete(key);
  }

  private clearQuote(entry: InFlightEntry, owner: object): void {
    if (entry.quoteOwner !== owner) return;
    delete entry.quote;
    delete entry.quoteOwner;
  }

  /**
   * Key of the per-chat commit queue. A slow hook chain for one message must not let a later message
   * of the same chat be stored and announced first, so the insert and dispatch of every message in a
   * chat (inbound and own-send echo alike) run in arrival order. Keyed on the engine's chatId, not
   * on a hook's rewrite.
   */
  private chatCommitKey(id: string, message: IncomingMessage): string {
    return `${id}:${message.chatId}`;
  }

  /**
   * The inbound message a `message:received` chain is carrying, as the chain last rewrote it, from the
   * moment the chain starts until the message's row is written; undefined otherwise. The row does not
   * exist while the chain runs, so a handler that replies to the message finds nothing to quote in the
   * table.
   */
  inFlightInbound(sessionId: string, waMessageId: string): Pick<IncomingMessage, 'chatId' | 'body'> | undefined {
    const entry = waMessageId ? this.inboundInFlight.get(`${sessionId}:${waMessageId}`) : undefined;
    // Admitted but not emitted yet: nobody can have heard of it, so it has nothing to lend.
    if (!entry?.quote) return undefined;
    // A revoked message lends no text, as its cleared row would not; the chatId still scopes the quote.
    return entry.revoked ? { chatId: entry.quote.chatId, body: '' } : entry.quote;
  }

  /**
   * The message a `message:received` / `message:sent` hook chain handed back, or a fresh copy of the
   * engine's message when it is not one: null, a primitive, or an object without the `id` and `chatId`
   * every row and dispatch keys on. HookManager already skips such a result per handler
   * ({@link isMessagePayload}), keeping an earlier handler's rewrite; this is the last guard. A plugin
   * returning `data: null` to mean "I consumed it" used to throw below and erase the message from
   * history, webhooks and the websocket. A plugin may rewrite a message; it cannot make the gateway
   * forget it (see {@link prepareInboundMessage}).
   */
  private messageOrEngineCopy(
    id: string,
    event: 'message:received' | 'message:sent',
    data: unknown,
    message: IncomingMessage,
  ): InboundMessageData {
    const candidate = data as Partial<IncomingMessage> | null;
    if (isMessagePayload(candidate)) {
      return candidate as InboundMessageData;
    }
    this.logger.warn(`A ${event} hook returned a payload that is not a message; using the engine's copy`, {
      sessionId: id,
      messageId: message.id,
      received: candidate === null ? 'null' : typeof candidate,
      action: 'hook_message_discarded',
    });
    const copy = { ...message };
    delete copy.originalBody;
    return copy;
  }

  /** `isStatusBroadcast` arm of {@link handleInboundMessage}: ingest into the status store, not the message pipeline. */
  private ingestInboundStatus(id: string, engine: IWhatsAppEngine, message: IncomingMessage): Promise<void> {
    // Status/Story posts arrive via the inbound path for some engines; ingest them into the
    // status store instead of the message pipeline. Mirrors the isStatusBroadcast guard in
    // onMessageCreate below: an own-send echo (fromMe) stays a plain drop — never ingested,
    // never dispatched — so a status you posted never re-appears in your own webhooks/API as
    // if a contact had posted it.
    if (message.fromMe) return Promise.resolve();
    const status = buildIncomingStatus(message);
    if (!status) return Promise.resolve();
    return (
      this.statusStore
        .ingest(id, status)
        // Dispatch only on a fresh insert: ingest also resolves with the pre-existing row
        // for a duplicate delivery (or the winner's row after a lost insert race), and the
        // webhook must fire once per status, not once per (re)delivery.
        .then(({ row, created }) => {
          // The ingest awaited; a stop()/delete() can retire this engine mid-flight — don't
          // dispatch for a session that no longer exists (mirrors message.received's re-check).
          if (!this.engines.isLive(id, engine)) return;
          // One that expired while the ingest ran (a slow media write) is gone from every read: announcing it
          // would point a consumer at a status the API no longer serves.
          if (created && row.expiresAt > Date.now()) this.dispatchStatusReceived(id, row);
        })
        .catch(err =>
          this.logger.warn('Status ingest failed', {
            sessionId: id,
            error: err instanceof Error ? err.message : String(err),
          }),
        )
    );
  }

  /** Operator opt-out gate for disappearing messages: true when the message must be skipped entirely. */
  private shouldSkipEphemeralMessage(id: string, message: IncomingMessage): boolean {
    // Ephemeral/disappearing messages: skip persist + dispatch when the operator opted out.
    // A message is ephemeral when its chat has a disappearing-messages timer (ephemeralDuration > 0).
    if (
      !resolveFeatureFlags(this.configService).storeEphemeralMessages &&
      message.ephemeralDuration &&
      message.ephemeralDuration > 0
    ) {
      this.logger.debug('Skipping ephemeral message', {
        sessionId: id,
        messageId: message.id,
        chatId: message.chatId,
        ephemeralDuration: message.ephemeralDuration,
      });
      return true;
    }
    return false;
  }

  /** Post-hook continuation of {@link handleInboundMessage} that may run concurrently: resolve the sender. */
  private async prepareInboundMessage(id: string, finalMessage: InboundMessageData): Promise<InboundMessageData> {
    // `continue: false` is deliberately NOT read here. It means "stop the handler chain", which
    // HookManager has already done — the plugins after the one that returned it never ran. It
    // does not mean "this message never happened".
    //
    // Honouring it here used to skip everything below: the message was never written to the
    // messages table, never dispatched to webhooks, and never emitted over the websocket. An
    // auto-reply plugin returning `false` for its ordinary purpose — keeping other bots from
    // answering the same message — silently erased the customer's message from the operator's
    // own history, leaving a thread of bot replies answering nothing. Nothing in the hook
    // contract (`HookResult.continue`, docs/19) or the webhook contract (`message.received`
    // fires when "an inbound message arrives", docs/06) hinted at that, and a sandboxed
    // marketplace plugin could swallow a session's entire inbound traffic with no audit trail.
    //
    // The message has already arrived at WhatsApp. A plugin can stop other plugins from acting
    // on it; it cannot make the gateway forget it. Pre-action hooks are where a veto belongs —
    // `message:sending` blocks a send that has not happened yet (core/hooks/sending-gate.ts).

    // Persist the incoming message so the dashboard chats view can render history.
    const incoming: IncomingMessage = finalMessage;

    // Inline @lid -> phone resolution (#263), opt-in via RESOLVE_LID_TO_PHONE. Best-effort:
    // attaches senderPhone (digits or null) before persist/dispatch so webhook/ws consumers
    // get it in a single pass. Only for privacy-id senders, so no lookup for normal numbers.
    if (resolveFeatureFlags(this.configService).resolveLidToPhone && incoming.isLidSender && !incoming.fromMe) {
      incoming.senderPhone = await this.lidResolver.resolveSenderPhone(id, incoming.author ?? incoming.from);
    }
    return finalMessage;
  }

  /** Per-chat, in-order stage of {@link handleInboundMessage}: persist, then dispatch. */
  private async commitInboundMessage(
    id: string,
    engine: IWhatsAppEngine,
    finalMessage: InboundMessageData,
    entry: InFlightEntry,
  ): Promise<InboundOutcome | undefined> {
    const outcome = await this.persistInboundMessage(id, engine, finalMessage, entry);
    if (outcome === 'repeat') return this.judgeRepeat(id, finalMessage);
    if (outcome) this.dispatchInboundMessage(id, finalMessage, outcome, entry);
    return undefined;
  }

  /**
   * Whether a message the insert refused as a repeat is another message than the one holding its id.
   * A re-fire of the same message is not, but an id reused from another chat, another side of the
   * conversation or another author of a group is: the engine is told, so its copy under that id does
   * not stand in for the stored message. Judged by the rule that refuses a change aimed at the row, so
   * what that rule would refuse to edit is not this message. A row that cannot be read, or that does
   * not prove a difference, says nothing and the engine keeps its copy.
   */
  private async judgeRepeat(id: string, message: InboundMessageData): Promise<InboundOutcome | undefined> {
    const reason = await this.mutationProjector.foreignRowReason(
      id,
      storableWaMessageId(message.id) ?? '',
      claimOf(message),
    );
    if (!reason) return undefined;
    this.logger.warn('Dropping a message that reuses the id of a different stored message', {
      sessionId: id,
      messageId: message.id,
      reason,
      action: 'message_id_reused',
    });
    return { conflict: true };
  }

  /**
   * Build the inbound row and insert it under the UNIQUE dedup oracle. Returns the row plus whether
   * the insert landed, 'repeat' when the id already has a row (an engine re-fire, or another message
   * under the same id), or null when the pipeline must stop (stale engine).
   */
  private async persistInboundMessage(
    id: string,
    engine: IWhatsAppEngine,
    incoming: IncomingMessage,
    entry: InFlightEntry,
  ): Promise<InboundPersistOutcome | 'repeat' | null> {
    const metadata = buildMessageMetadata(incoming);

    const chatName = incoming.contact?.pushName ?? incoming.contact?.name ?? undefined;

    const dbMessage = this.messageRepository.create({
      sessionId: id,
      waMessageId: storableWaMessageId(incoming.id),
      chatId: incoming.chatId,
      chatName,
      // Group poster (participant JID) — `from` is the group JID, so this is the stable
      // sender identity the chat view keys attribution runs/colors on. Undefined for 1:1.
      author: incoming.author,
      from: incoming.from,
      to: incoming.to,
      body: incoming.body,
      type: incoming.type,
      direction: incoming.fromMe ? MessageDirection.OUTGOING : MessageDirection.INCOMING,
      timestamp: incoming.timestamp,
      status: MessageStatus.SENT,
      metadata,
    });

    // The hook chain above is async; a delete()/teardown can retire this engine while it
    // awaits. Re-check liveness so a late continuation can't persist an orphan messages row
    // (the row has no FK, so a session-delete cleanup would never reap it) or dispatch for a
    // session that no longer exists. Mirrors the synchronous isLiveEngine gate at entry.
    await this.waitForInFlightChanges(id, incoming.id);
    if (!this.engines.isLive(id, engine)) return null;
    const insertedCleared = this.applyHeldChanges(dbMessage, entry);

    // De-duplicate at the source: the engine can re-fire `message` for one inbound message
    // (#464). UNIQUE(sessionId, waMessageId) makes the insert the atomic dedup oracle — a
    // near-simultaneous re-fire loses the race and is skipped here, so persist + webhook + WS
    // happen exactly once. Fail-open: a non-conflict DB error still dispatches, so a real
    // message is never dropped by a transient DB failure.
    const outcome = await this.insertWithRetry(id, engine, dbMessage, 'incoming');
    await this.waitForInFlightChanges(id, incoming.id);
    if (!this.engines.isLive(id, engine)) return null;
    if (outcome.landed === 'yes') {
      this.applyChangesMadeInFlight(id, incoming.id, entry, insertedCleared);
      return { dbMessage, persisted: true };
    }
    if (outcome.landed === 'stale') return null;
    // A duplicate on the first attempt is a re-fire: the original already persisted and dispatched.
    // A duplicate on the retry is ambiguous: the first attempt may have committed before its error,
    // in which case nothing dispatched yet, so dispatch fail-open (without the row-bound hook), and
    // that row still has to take a revoke or edit that arrived in flight.
    if (outcome.landed === 'dup' && outcome.retried) {
      this.applyChangesMadeInFlight(id, incoming.id, entry, false, claimOf(incoming));
    }
    // A delivery that came deleted clears the row it lost to, as a revoke does, once the row proves to be the message.
    if (outcome.landed === 'dup' && incoming.type === 'revoked') {
      void this.recordRevoke(id, incoming.id, claimOf(incoming));
    }
    if (outcome.landed === 'dup' && !outcome.retried) return 'repeat';
    return { dbMessage, persisted: false };
  }

  /**
   * A revoke or edit can arrive while a message waits for its hook or insert: write
   * the row as the change leaves it, so `message:persisted` and the media archive never see content
   * that was taken back. A change landing during the insert is still applied after it. A message
   * delivered deleted is written cleared on either database, as the history sync stores one, and takes
   * no edit. Returns whether the row is written cleared.
   */
  private applyHeldChanges(dbMessage: Message, entry: InFlightEntry): boolean {
    if (dbMessage.type === 'revoked') {
      Object.assign(dbMessage, REVOKED_ROW_PATCH);
      return true;
    }
    if (entry?.revoked) Object.assign(dbMessage, REVOKED_ROW_PATCH);
    else {
      if (entry?.editedBody !== undefined) dbMessage.body = entry.editedBody;
      if (entry?.edited) dbMessage.metadata = { ...dbMessage.metadata, edited: true };
    }
    return entry?.revoked === true;
  }

  /**
   * Insert a message row under the UNIQUE(sessionId, waMessageId) dedup oracle. `insert()` (not
   * `save()`) is load-bearing: a duplicate insert throws, which is the atomic dedup oracle for #464
   * re-fires. A transient failure is retried once after {@link PERSIST_RETRY_DELAY_MS}, re-checking
   * that the engine is still live so a retired session never gets an orphan row. On success the
   * DB-generated columns are merged onto `dbMessage`.
   */
  private async insertWithRetry(
    id: string,
    engine: IWhatsAppEngine,
    dbMessage: Message,
    direction: 'incoming' | 'outgoing',
  ): Promise<InsertOutcome> {
    const label = `Failed to save ${direction} message ${dbMessage.waMessageId} to database`;
    const insert = async (): Promise<InsertOutcome> => {
      // Registered with the session's write scope, so a delete drains an insert already under way before it
      // removes the session's rows; the row has no foreign key to refuse one that lands afterwards.
      const writes = captureSessionWrites(this.messageRepository.manager?.connection ?? this.messageRepository, id);
      const result = await writes
        .write(() => this.messageRepository.insert(dbMessage as unknown as QueryDeepPartialEntity<Message>))
        .finally(() => writes.close());
      // `insert()` (not `save()`) does NOT merge DB-generated columns (@PrimaryGeneratedColumn,
      // @CreateDateColumn) back onto the entity instance — so merge them explicitly here, before
      // the `message:persisted` emit. `identifiers[0]` always carries the PK on both SQLite and
      // Postgres; `generatedMaps[0]` adds createdAt where the driver returns it (Postgres yes;
      // SQLite historically does not — acceptable; the PK is the load-bearing field for plugins).
      Object.assign(dbMessage, result.identifiers[0] ?? {}, result.generatedMaps?.[0] ?? {});
      return { landed: 'yes' };
    };
    try {
      return await insert();
    } catch (err) {
      if (isUniqueViolation(err)) return { landed: 'dup', retried: false };
      if (!isTransientDbError(err)) {
        this.logger.error(label, String(err));
        return { landed: 'failed' };
      }
      this.logger.warn(`${label}, retrying once`, { sessionId: id, error: String(err) });
    }
    await new Promise(resolve => setTimeout(resolve, PERSIST_RETRY_DELAY_MS));
    if (!this.engines.isLive(id, engine)) return { landed: 'stale' };
    try {
      return await insert();
    } catch (err) {
      if (isUniqueViolation(err)) return { landed: 'dup', retried: true };
      this.logger.error(label, String(err));
      return { landed: 'failed' };
    }
  }

  /**
   * Write a revoke, edit, reaction or ack that arrived before the message's row existed onto the row
   * just inserted: its own write matched no row then. Queued on the message's mutation chain, so it
   * lands after any edit already queued, and a revoke wins over the rest. A change arriving after the
   * insert finds the row itself. Reactions are only stored here; their event already went out. A row
   * inserted cleared is cleared again, in case a change raced the insert, without announcing it:
   * `message:persisted` already carried it cleared. Where the insert lost, a pending revoke announces the
   * row it clears, which an earlier revoke may have cleared and announced already, and a revoke event still
   * waiting for its own row read when the insert lands announces it once more: a consumer may see the
   * cleared row more than once under the same id.
   *
   * `lostInsert`, set when the delivery's insert lost to a row under the id, says what the delivery claims
   * to be. That row may be the message itself (its first attempt committed before the error) or another
   * message's (an id reused from another chat): the changes go to it only if it is the message. The
   * judgement is the first step of the slot taken on the chain here, not a read ahead of it, so a change
   * of the message that arrives while the row is read queues behind the write instead of being
   * overwritten by it.
   */
  private applyChangesMadeInFlight(
    id: string,
    waMessageId: string,
    pending: InFlightEntry,
    insertedCleared = false,
    lostInsert?: MutationSource,
  ): void {
    const { ackStatus } = pending;
    const rowChanges = Boolean(
      pending.revoked || pending.editedBody !== undefined || pending.edited || pending.reactions,
    );
    if (!ackStatus && !rowChanges) return;
    const advance = (): void => {
      if (!ackStatus) return;
      void this.advanceAck(id, waMessageId, ackStatus).catch(err =>
        this.logger.error(`Failed to advance ack for ${waMessageId}`, String(err)),
      );
    };
    if (!lostInsert) {
      advance();
      if (rowChanges) {
        this.enqueueMessageMutation(id, waMessageId, () =>
          this.writeChangesMadeInFlight(id, waMessageId, pending, insertedCleared),
        );
      }
      return;
    }
    this.enqueueMessageMutation(id, waMessageId, async () => {
      const reason = await this.mutationProjector.foreignRowReason(id, waMessageId, lostInsert);
      if (reason) {
        this.logger.warn('Not applying the changes of a message to the stored message that holds its id', {
          sessionId: id,
          messageId: waMessageId,
          reason,
        });
        return;
      }
      advance();
      await this.writeChangesMadeInFlight(id, waMessageId, pending, insertedCleared);
    });
  }

  /** The row part of {@link applyChangesMadeInFlight}. Must run on the mutation chain. */
  private async writeChangesMadeInFlight(
    id: string,
    waMessageId: string,
    pending: InFlightEntry,
    insertedCleared: boolean,
  ): Promise<void> {
    if (pending.revoked) return this.revokeRow(id, waMessageId, !insertedCleared);
    try {
      // Never onto a revoked row, as the edit paths: a message delivered deleted, or deleted before it, stays cleared.
      if (pending.editedBody !== undefined) {
        await this.messageRepository.update(
          { sessionId: id, waMessageId, type: Not('revoked') },
          { body: pending.editedBody },
        );
      }
      if (pending.reactions) await this.storeReactions(id, waMessageId, pending.reactions);
      // The marker an edit of a stored row leaves, written last so a lost metadata race costs it alone.
      if (pending.edited) await this.mutationProjector.markMessageEdited(id, waMessageId);
    } catch (err) {
      this.logger.error(`Failed to apply changes to message ${waMessageId}`, String(err));
    }
  }

  /** Merge reactions into the row's metadata, withdrawing a sender's on ''. Must run on the mutation chain. */
  private async storeReactions(id: string, waMessageId: string, changes: Record<string, string>): Promise<void> {
    await updateMessageMetadata(this.messageRepository, { sessionId: id, waMessageId }, metadata => {
      const reactions = { ...(metadata.reactions as Record<string, string> | undefined) };
      for (const [sender, reaction] of Object.entries(changes)) {
        if (reaction) reactions[sender] = reaction;
        else delete reactions[sender];
      }
      return { ...metadata, reactions };
    });
  }

  /**
   * Clear a revoked message's stored row, on the message's mutation chain so a reaction or edit queued
   * before it cannot write content back afterwards. Used by the engine's revoke event, by the REST
   * delete, and by a delivery that came deleted and lost its insert. Best-effort like every stored-message
   * mutation: never rejects, and resolves once the write has run.
   *
   * With `source`, the caller has not had the stored row judge the revoke yet: the message still arriving
   * is taken back only if the revoke agrees with it, and the row is cleared only if the revoke is not
   * foreign to it. Without one, the revoke was judged by the caller (the engine's revoke event is).
   */
  recordRevoke(sessionId: string, waMessageId: string, source?: MutationSource, announced = false): Promise<void> {
    let stored: Promise<void> | undefined;
    const pending = this.changeInFlight(sessionId, waMessageId, source, (needsRow, entry) => {
      if (entry && !needsRow) {
        this.holdRevoked(sessionId, entry);
        if (announced) entry.revokeAnnounced = true;
      }
      stored = new Promise(resolve =>
        this.enqueueMessageMutation(sessionId, waMessageId, () =>
          this.revokeRow(sessionId, waMessageId, true, source).finally(resolve),
        ),
      );
    });
    return Promise.resolve(pending).then(() => stored);
  }

  /** Take back a message not written yet: its row is stored cleared, and media waiting for room needs none. */
  private holdRevoked(sessionId: string, entry: InFlightEntry): void {
    entry.revoked = true;
    for (const t of this.tickets.get(sessionId) ?? []) if (t.entry === entry) t.giveUp();
  }

  /**
   * Apply {@link REVOKED_ROW_PATCH}, then hand the cleared row to `message:persisted` so a plugin index
   * keyed by row id drops the content too. Must run on the message's mutation chain. The row is the
   * table's one under the id, which another chat's message may hold: a `source` that the row proves
   * foreign leaves it alone.
   */
  private async revokeRow(
    sessionId: string,
    waMessageId: string,
    notify = true,
    source?: MutationSource,
  ): Promise<void> {
    // An undefined condition is DROPPED from the where-clause, which would clear every row of the session.
    if (!waMessageId) return;
    try {
      const reason = source && (await this.mutationProjector.foreignRowReason(sessionId, waMessageId, source));
      if (reason) {
        this.logger.warn('Dropping a revoke aimed at a message of another chat or sender', {
          sessionId,
          messageId: waMessageId,
          reason,
        });
        return;
      }
      const result = await this.messageRepository.update({ sessionId, waMessageId }, REVOKED_ROW_PATCH);
      this.markedEdited.get(sessionId)?.delete(waMessageId);
      if (!result?.affected || !notify) return;
      const row = await this.messageRepository.findOne({ where: { sessionId, waMessageId } });
      if (!row) return;
      void this.hookManager
        .execute('message:persisted', { sessionId, message: row }, { sessionId, source: 'SessionService' })
        .catch(() => undefined);
    } catch (err) {
      this.logger.error(`Failed to clear revoked message ${waMessageId}`, String(err));
    }
  }

  /** Fan an accepted inbound message out: `message:persisted` plugin hook, webhook, websocket emit. */
  private dispatchInboundMessage(
    id: string,
    finalMessage: InboundMessageData,
    outcome: InboundPersistOutcome,
    entry: InFlightEntry,
  ): void {
    const { dbMessage, persisted } = outcome;
    // Fire-and-forget: a plugin handler must never break the receive path. Both engine adapters
    // (wwjs `message` and Baileys `upsert`) converge on this persist, so one emit covers inbound.
    // The built-in FTS search provider is DB-synced and does NOT consume this; it exists for
    // plugin providers (Spec 2) + general use.
    // Gate ONLY the hook on `persisted`: on a non-unique insert error (transient SQLITE_BUSY /
    // lock-timeout / connection drop) the row was never stored and `dbMessage.id` is undefined,
    // so emitting `message:persisted` would hand plugins an id-less payload for a row that isn't
    // in the DB. The webhook/WS dispatch below stays fail-open — a real inbound message must
    // never be dropped on a transient DB failure; only the hook requires a durable row.
    if (persisted) {
      void this.hookManager
        .execute(
          'message:persisted',
          { sessionId: id, message: dbMessage },
          { sessionId: id, source: 'SessionService' },
        )
        .catch(() => undefined);

      // Fire-and-forget for the same reason as the hook above: the receive path must not wait on
      // storage. Gated on `persisted` because the archive updates the row by id, and on a failed
      // insert there is no row to point at the file. A no-op unless archiving is enabled.
      void this.chatMediaArchive?.archive(dbMessage).catch(() => undefined);
    }

    const announced = this.withChangesMadeInFlight(finalMessage, entry);
    if (!announced) return;
    // Dispatch to webhooks with potentially modified message
    void this.webhookService.dispatch(id, 'message.received', announced);
    // Autoreply rules ride the same at-most-once dispatch (the insert oracle above dedupes engine
    // re-fires) and stay fail-open like the webhook: a broken rule must never break the receive path.
    void this.automationRules?.evaluateInbound(id, announced).catch(() => undefined);
    // Emit real-time event to WebSocket clients
    this.eventsGateway.emitMessage(id, announced);
  }

  /**
   * The message as a revoke or edit that arrived while it was in flight left it, for its announcement:
   * null once the engine revoked it (message.revoked already went out, so the deleted content is not
   * announced after it), the revoked placeholder when only the REST delete did (a delete-for-me emits no
   * engine revoke, and the message still exists for its sender) or when it was delivered deleted, the edited
   * body when edited (message.edited already went out with it), plus `edited: true` when the row is marked
   * for it or already was (`rowMarked`): a consumer that held no copy of the message could not apply that
   * event. The stored row takes the same changes in {@link applyChangesMadeInFlight}. One delivered deleted
   * is stored cleared and takes no edit ({@link applyHeldChanges}), and clears the row it lost its insert to
   * when that row is the message.
   */
  private withChangesMadeInFlight(
    message: InboundMessageData,
    pending: InFlightEntry,
    rowMarked = false,
  ): (InboundMessageData & { edited?: true }) | null {
    if (pending?.revokeAnnounced) return null;
    // No edit held for it, and no mark.
    if (pending?.revoked || message.type === 'revoked') return deletedPlaceholder(message);
    const edited = rowMarked || pending?.edited;
    // An edit the engine applied before the hand-over is in the body already.
    if (pending?.editedBody === undefined) return edited ? { ...message, edited: true as const } : message;
    return { ...message, body: pending.editedBody, ...(edited ? { edited: true as const } : {}) };
  }

  /** Engine callback body, lifted out of initializeEngine so the wiring table stays readable. */
  handleOwnSendEcho(id: string, engine: IWhatsAppEngine, message: IncomingMessage, ticket?: InboundTicket): void {
    const turn = ticket instanceof InboundTurn ? ticket : undefined;
    try {
      this.receiveOwnSendEcho(id, engine, message, turn);
    } finally {
      turn?.drop();
    }
  }

  /** {@link handleOwnSendEcho} with the ticket resolved; every early return leaves the ticket to be dropped. */
  private receiveOwnSendEcho(id: string, engine: IWhatsAppEngine, message: IncomingMessage, turn?: InboundTurn): void {
    if (!this.engines.isLive(id, engine)) return;
    // `message_create` fires for every message the account creates, including sends composed on a
    // linked phone — which the `message`/`onMessage` event never delivers. Incoming messages are
    // already handled by `onMessage`, so only outgoing (`fromMe`) ones produce `message.sent` here.
    if (!message.fromMe) {
      return;
    }

    // Status/Story posts are account-created but not real conversations; don't emit `message.sent`
    // for them. The adapter flags these (the engine-specific pseudo-JID stays out of this layer).
    if (message.isStatusBroadcast) {
      return;
    }

    this.logger.debug(`Message sent to ${message.to}`, {
      sessionId: id,
      messageId: message.id,
      to: message.to,
      action: 'message_sent',
    });
    // Update last active timestamp
    void this.sessionRepository.update(id, { lastActiveAt: new Date() }).catch(() => undefined);
    // As on the inbound path, one delivered deleted reaches the hooks with no content.
    const messageData = message.type === 'revoked' ? deletedPlaceholder(message) : { ...message };
    delete messageData.originalBody;

    const onFailure = (err: unknown): null => {
      this.logger.error(`onMessageCreate handler failed for ${id}`, String(err));
      return null;
    };
    // The commit may wait behind a slow earlier message of the chat; a revoke, edit or ack of this
    // send landing meanwhile is recorded here and applied once the row is written. Like the inbound
    // path, the entry follows the chain's rewrites, so a quote carries what the row will hold.
    const inFlightKey = `${id}:${message.id}`;
    const inFlight = turn
      ? Object.assign(turn.entry, { ref: turn.entry.ref ?? refOf(messageData) })
      : this.trackInFlight(inFlightKey, messageData);
    const delivery = {
      entry: inFlight,
      body: message.originalBody ?? message.body,
      edited: message.originalBody !== undefined,
    };
    const quoteOwner = {};
    // Execute hook for message sent - plugins can modify or stop processing. Like the inbound path,
    // the hook chain runs concurrently and the commit waits its turn on the chat's queue.
    const prepared = this.startHookChain(id, engine, turn, messageData, delivery, quoteOwner, messageData =>
      this.hookManager
        .execute('message:sent', messageData, {
          sessionId: id,
          source: 'Engine',
          accept: data => {
            if (!isMessagePayload(data)) return false;
            if (delivery.entry.quoteOwner === quoteOwner) delivery.entry.quote = quoteOf(data);
            return true;
          },
        })
        .then(({ data }) => this.messageOrEngineCopy(id, 'message:sent', data, messageData)),
    ).catch(onFailure);
    this.commitInTurn(id, message, turn, async () => {
      try {
        const finalMessage = await prepared;
        if (finalMessage) await this.commitOwnSendEcho(id, engine, finalMessage, delivery.entry);
      } catch (err) {
        onFailure(err);
      } finally {
        this.clearQuote(delivery.entry, quoteOwner);
        if (!turn) this.untrackInFlight(inFlightKey, inFlight);
      }
    });
  }

  /** Per-chat, in-order stage of {@link handleOwnSendEcho}: persist, then dispatch `message.sent`. */
  private async commitOwnSendEcho(
    id: string,
    engine: IWhatsAppEngine,
    finalMessage: InboundMessageData,
    entry: InFlightEntry,
  ): Promise<void> {
    // `continue: false` is not read here, for the same reason as the message:received path
    // above: the send has already happened, so a plugin can stop the handler chain but cannot
    // un-send it. Skipping the persist below dropped the operator's own outgoing message from
    // history and from `message.sent` webhooks.

    // Persist the outgoing message so local history reflects sends composed on a linked phone
    // (message_create is the ONLY event those produce). It also fires for API-originated sends,
    // which the REST send path persists itself; the UNIQUE(sessionId, waMessageId) index is
    // the atomic dedup oracle between the two writers: the loser skips its insert, and
    // persistSentState additionally drops its redundant PENDING row when the echo won. The
    // webhook/WS dispatch below is identical whether the insert won, lost, or failed: the
    // message.sent contract is unchanged.
    await this.waitForInFlightChanges(id, finalMessage.id);
    if (!this.engines.isLive(id, engine)) return;
    const outgoing: IncomingMessage = finalMessage;
    const metadata = buildMessageMetadata(outgoing, true);

    // The ephemeral opt-out gates STORAGE only (mirrors onMessage); the live dispatch below
    // is today's contract and stays.
    const mayPersist =
      resolveFeatureFlags(this.configService).storeEphemeralMessages ||
      !(outgoing.ephemeralDuration && outgoing.ephemeralDuration > 0);

    let rowMarked = false;
    if (mayPersist) {
      const dbMessage = this.messageRepository.create({
        sessionId: id,
        waMessageId: storableWaMessageId(outgoing.id),
        chatId: outgoing.chatId,
        from: outgoing.from,
        to: outgoing.to,
        body: outgoing.body,
        type: outgoing.type,
        direction: MessageDirection.OUTGOING,
        timestamp: outgoing.timestamp,
        status: MessageStatus.SENT,
        metadata,
      });
      // The hook chain above is async; a delete()/teardown can retire this engine while it
      // awaits. Re-check liveness so a late continuation can't persist an orphan row
      // (mirrors onMessage).
      if (!this.engines.isLive(id, engine)) return;
      const insertedCleared = this.applyHeldChanges(dbMessage, entry);
      // A unique violation means the REST send path already persisted this API-originated
      // send: the dedup oracle working as intended, not an error. Any other failure (after the
      // one transient retry) fails open, so a real send is never dropped on a DB fault.
      const outcome = await this.insertWithRetry(id, engine, dbMessage, 'outgoing');
      await this.waitForInFlightChanges(id, outgoing.id);
      if (!this.engines.isLive(id, engine)) return;
      if (outcome.landed === 'stale') return;
      // The REST writer may have won either attempt; its row still takes the echo's pending changes.
      if (outcome.landed === 'dup') {
        this.applyChangesMadeInFlight(id, outgoing.id, entry, false, claimOf(outgoing));
        // A delivery that came deleted clears that row, as a revoke does, once the row proves to be the message.
        if (outgoing.type === 'revoked') void this.recordRevoke(id, outgoing.id, claimOf(outgoing));
        // That row may be older than this delivery and edited since, the edit still being written: announced once the
        // changes queued for the message have run, with the mark they left.
        rowMarked = await new Promise<boolean>(resolve =>
          this.enqueueMessageMutation(id, outgoing.id, async () => {
            const marked = this.markedEdited.get(id)?.has(outgoing.id) === true;
            const foreign =
              marked && (await this.mutationProjector.foreignRowReason(id, outgoing.id, claimOf(outgoing)));
            resolve(marked && !foreign);
          }),
        );
      }
      if (outcome.landed === 'yes') {
        // The id had no row, so a mark remembered for it was of a row removed since.
        this.markedEdited.get(id)?.delete(outgoing.id);
        this.applyChangesMadeInFlight(id, outgoing.id, entry, insertedCleared);
        // Fire-and-forget, mirroring onMessage: plugin providers (search etc.) see phone-
        // composed sends exactly like API sends.
        void this.hookManager
          .execute(
            'message:persisted',
            { sessionId: id, message: dbMessage },
            { sessionId: id, source: 'SessionService' },
          )
          .catch(() => undefined);

        // Archive this send's media, mirroring onMessage. This is the ONLY path a phone-composed
        // send takes, so the REST-side chokepoint would never see it. Opt-in twice over
        // (CHAT_MEDIA_ARCHIVE_ENABLED + _OUTBOUND) and a no-op otherwise; archive() itself
        // refuses a row that is already archived, so the REST writer racing us costs at most one
        // duplicate file write, which archive() deletes because the first pointer wins.
        if (this.configService?.get<boolean>('chatMedia.archiveOutbound', false) === true) {
          void this.chatMediaArchive?.archive(dbMessage).catch(() => undefined);
        }
      }
    }

    if (!this.engines.isLive(id, engine)) return;
    const sent = this.withChangesMadeInFlight(finalMessage, entry, rowMarked);
    if (!sent) return;
    void this.webhookService.dispatch(id, 'message.sent', sent);
    // Emit real-time event to WebSocket clients (as message.sent, not message.received)
    this.eventsGateway.emitMessageSent(id, sent);
  }

  /** Engine callback body, lifted out of initializeEngine so the wiring table stays readable. */
  handleMessageAck(
    id: string,
    engine: IWhatsAppEngine,
    messageId: string,
    status: DeliveryStatus,
    chatId?: string,
  ): void {
    if (!this.engines.isLive(id, engine)) return;
    this.logger.debug(`Message ack: ${messageId} -> ${status}`, {
      sessionId: id,
      messageId,
      status,
      action: 'message_ack',
    });

    // Reflect real delivery state on the stored message (#220): delivered/read/failed advance the
    // stored status; pending/sent carry no upgrade (it's already SENT — visibly "not delivered").
    // The UPDATE is guarded to the allowed prior statuses so delivery state only ADVANCES: an
    // out-of-order/late ack cannot downgrade a higher status, which also makes these
    // fire-and-forget writes race-safe at the DB level.
    const messageStatus = deliveryStatusToMessageStatus(status);
    if (messageStatus) {
      // A message not written yet (its commit waits behind an earlier one of the chat) keeps the
      // furthest ack for when its row lands; the UPDATEs below would match nothing.
      const inFlight = this.inboundInFlight.get(`${id}:${messageId}`);
      if (inFlight && (!inFlight.ackStatus || ackStatusTransitionFrom(messageStatus).includes(inFlight.ackStatus))) {
        inFlight.ackStatus = messageStatus;
      }
      const advanceAck = (): Promise<number> => this.advanceAck(id, messageId, messageStatus);

      const logNoop = (): void =>
        this.logger.debug(`Message ack ${messageId}: no status row advanced to ${messageStatus} (${status})`, {
          sessionId: id,
          messageId,
          status,
          action: 'message_ack_noop',
        });

      const onAckError = (err: unknown): void =>
        this.logger.error(`Failed to advance ack for ${messageId}`, String(err));

      void advanceAck()
        .then(affected => {
          if (affected > 0) return;
          // affected:0 — most likely the send's 2nd save (which writes waMessageId) hasn't committed
          // yet, so the row isn't matchable. Each ack is one-shot (WhatsApp won't necessarily resend),
          // so retry ONCE after a short delay to close that race rather than leave it stuck at SENT.
          const timer = setTimeout(() => {
            void advanceAck()
              .then(retried => {
                if (retried === 0) logNoop();
              })
              .catch(onAckError);
          }, ACK_RECONCILE_DELAY_MS);
          timer.unref?.();
        })
        .catch(onAckError);
    }

    // One ack payload, emitted identically over the socket and the webhook so a client coded
    // against either channel sees the same shape. `id` mirrors the field every other message.*
    // event carries (and the idempotency-key resolver reads). `ack` is a deprecated legacy field
    // kept for backward compatibility — new consumers should read the neutral `status`. `chatId`
    // rides along when the engine's update names the chat, so a webhook `chatId` condition scopes
    // ack and failure events to that chat instead of suppressing them outright.
    const ackPayload = {
      id: messageId,
      messageId,
      status,
      ack: deliveryStatusToAck(status),
      ...(chatId ? { chatId } : {}),
    };

    // Push the live delivery/read tick to the dashboard over the websocket.
    this.eventsGateway.emitMessageAck(id, ackPayload);

    // Dispatch the delivery/read receipt to webhooks (#155). Outgoing `message.sent` is handled
    // solely by `onMessageCreate`, so the ack path deliberately does NOT emit `message.sent`.
    void this.webhookService.dispatch(id, 'message.ack', ackPayload);

    // Surface delivery failures actively so consumers don't have to poll for them (#220). Use a
    // distinct object (not the shared ackPayload) so this separate event can't be perturbed by an
    // in-place payload mutation in the concurrent message.ack dispatch's webhook:before hook.
    if (status === 'failed') {
      void this.webhookService.dispatch(id, 'message.failed', { ...ackPayload });
    }

    // Notify plugins of the delivery/read receipt. The `message:ack` hook event was declared in
    // the HookEvent union but never emitted, so any plugin registered for it silently never fired.
    // Fire-and-forget: an ack is a notification with nothing downstream to cancel, so the hook's
    // `continue` flag is moot. Delivery failures surface here as status `failed` — `message:failed`
    // stays reserved for send-time send failures, which carry a distinct `{ error, input }` payload.
    void this.hookManager.execute(
      'message:ack',
      { messageId, status, ack: deliveryStatusToAck(status) },
      { sessionId: id, source: 'Engine' },
    );
  }

  /**
   * Engine callback body for one recipient's receipt (Baileys group and status messages). Nothing is
   * stored: the event is forwarded as is, over the socket and the webhook with the same shape. `id`
   * mirrors the other message.* events (and is what the idempotency-key resolver reads); `chatId` lets
   * webhook chatId filters scope it.
   */
  handleMessageReceipt(id: string, engine: IWhatsAppEngine, event: MessageReceiptEvent): void {
    if (!this.engines.isLive(id, engine)) return;
    const payload = {
      id: event.messageId,
      messageId: event.messageId,
      chatId: event.chatId,
      participant: event.participant,
      status: event.status,
      timestamp: event.timestamp,
    };
    this.eventsGateway.emitMessageReceipt(id, payload);
    void this.webhookService.dispatch(id, 'message.receipt', payload);
  }

  /**
   * Advance a stored message's delivery status, returning the rows changed. Scoped by sessionId:
   * waMessageId is unique per account/chat, not global, so an ack on one session must never advance a
   * same-id row in another session. The In() guard makes the UPDATE forward-only (a late/out-of-order
   * ack can't downgrade) and idempotent on retry.
   */
  private advanceAck(id: string, messageId: string, messageStatus: MessageStatus): Promise<number> {
    return this.messageRepository
      .update(
        { sessionId: id, waMessageId: messageId, status: In(ackStatusTransitionFrom(messageStatus)) },
        { status: messageStatus },
      )
      .then(result => result.affected ?? 0);
  }

  /** Engine callback body, lifted out of initializeEngine so the wiring table stays readable. */
  handleMessageRevoked(
    id: string,
    engine: IWhatsAppEngine,
    message: RevokedMessage,
    actor?: { fromMe: boolean },
  ): void {
    if (!this.engines.isLive(id, engine)) return;
    this.logger.debug(`Message revoked: ${message.id}`, {
      sessionId: id,
      messageId: message.id,
      action: 'message_revoked',
    });

    // Clear the stored message (best-effort; the message may not be in the DB). The
    // dashboard renders the localized "message deleted" text, so no display string is
    // persisted here.
    //
    // Match on `revokedId` (the ORIGINAL deleted message's id) when present: on wwebjs
    // `message.id` is the revocation notification, which never matches a stored row.
    // `revokedId` falls back to `id` (Baileys, where the two are the same).
    const revokedWaMessageId = message.revokedId ?? message.id;
    const source = actor ? ({ kind: 'revoke', chatId: message.chatId, fromMe: actor.fromMe } as const) : undefined;
    const apply = (): void => {
      void this.recordRevoke(id, revokedWaMessageId, source, true);

      // Notify consumers regardless of whether the row existed: webhook (message.revoked
      // is a declared event) + the real-time dashboard stream.
      const revokedPayload = message as unknown as Record<string, unknown>;
      void this.webhookService.dispatch(id, 'message.revoked', revokedPayload);
      this.eventsGateway.emitMessageRevoked(id, revokedPayload);
    };
    // whatsapp-web.js reports only what WhatsApp Web itself accepted, so it passes no actor and is applied at
    // once: its ids name the chat, so no row of another chat can hold the id. An engine that applies no
    // validation to a revoke says who made it, and the stored row says whose message it names: a revoke the
    // row proves foreign is dropped, announcement included.
    if (!source) {
      apply();
      return;
    }
    void this.changeInFlight(id, revokedWaMessageId, source, (needsRow, inFlight) => {
      if (inFlight && !needsRow) {
        this.holdRevoked(id, inFlight);
        inFlight.revokeAnnounced = true;
      }
      void this.mutationProjector.storedRowVerdict(id, revokedWaMessageId, source).then(verdict => {
        if (!this.engines.isLive(id, engine)) return;
        if (verdict.reason || (needsRow && !verdict.exists)) {
          if (verdict.reason) {
            this.logger.warn('Dropping a revoke aimed at a message of another chat or sender', {
              sessionId: id,
              messageId: revokedWaMessageId,
              reason: verdict.reason,
            });
          }
          return;
        }
        apply();
      });
    });
  }

  /** History backfill persist, extracted to message-history-projector.ts (stateless function). */
  persistHistoryMessages(id: string, engine: IWhatsAppEngine, messages: IncomingMessage[]): Promise<IncomingMessage[]> {
    return persistHistoryMessages(
      this.messageRepository,
      this.configService,
      id,
      messages,
      this.logger,
      () => this.engines.isLive(id, engine),
      row => {
        if (!this.engines.isLive(id, engine)) return;
        void this.hookManager
          .execute('message:persisted', { sessionId: id, message: row }, { sessionId: id, source: 'SessionService' })
          .catch(() => undefined);
      },
      this.lidMappingStore ? jid => this.lidMappingStore!.findPhoneForLid(jid) : undefined,
    );
  }

  /** Reaction apply, queued on the per-message mutation chain — see MessageMutationProjector. */
  applyReactionQueued(id: string, event: ReactionEvent): void {
    void this.changeInFlight(id, event.messageId, { kind: 'reaction', chatId: event.chatId }, (needsRow, entry) => {
      if (entry && !needsRow) (entry.reactions ??= {})[event.senderId] = event.reaction ?? '';
      this.mutationProjector.applyReactionQueued(id, event, needsRow);
    });
  }

  /** Edit apply, queued on the per-message mutation chain. */
  applyMessageEditQueued(id: string, message: EditedMessage): void {
    const source = { kind: 'edit', chatId: message.chatId, fromMe: message.fromMe, author: message.author } as const;
    void this.changeInFlight(id, message.messageId, source, (needsRow, entry) => {
      if (entry && !needsRow) this.holdEdit(entry, message.body);
      this.mutationProjector.applyMessageEditQueued(id, message, needsRow);
    });
  }

  /**
   * Keep changes in arrival order while a cross-form identity waits for a reported directory pairing.
   * This chain only prepares changes; it never waits for a row write or for the message's commit.
   * Exact identities retain their synchronous path until a preceding change needs that lookup.
   */
  private changeInFlight(
    id: string,
    messageId: string,
    source: MutationSource | undefined,
    ready: (needsRow: boolean, entry?: InFlightEntry) => void,
  ): void | Promise<void> {
    const key = `${id}:${messageId}`;
    const entry = this.inboundInFlight.get(key);
    const foreign = entry?.ref && source?.chatId ? mutationTargetsForeignRow(entry.ref, source) : null;
    if (!entry?.changes?.pending && (!foreign || !this.lidMappingStore)) {
      ready(foreign !== null, entry);
      return;
    }
    const changes = (entry!.changes ??= {});
    const ref = entry!.ref;
    const engine = this.engines.get(id);
    const pending = (changes.pending ?? Promise.resolve())
      .then(async () => {
        if (this.engines.get(id) !== engine) return;
        const current = this.inboundInFlight.get(key);
        if (current?.changes !== changes || current.ref !== ref) return;
        const reason =
          current.ref && source?.chatId
            ? await mutationTargetsForeignRowPersisted(
                current.ref,
                source,
                this.lidMappingStore ? jid => this.lidMappingStore!.findPhoneForLid(jid) : undefined,
              )
            : null;
        // A repeated delivery may replace the entry while the lookup awaits; only its shared identity
        // and change chain may inherit the result. A new engine must never inherit an old callback.
        const target = this.inboundInFlight.get(key);
        if (this.engines.get(id) !== engine || target?.changes !== changes || target.ref !== ref) return;
        ready(reason !== null, target);
      })
      .catch(err => {
        this.logger.warn('Unable to prepare a change for an arriving message', { error: String(err) });
      });
    changes.pending = pending;
    void pending.finally(() => {
      if (changes.pending === pending) delete changes.pending;
    });
    return pending;
  }

  /** Drain only identity checks already queued for this message, including changes arriving during a check. */
  private waitForInFlightChanges(id: string, messageId: string): Promise<void> | undefined {
    const key = `${id}:${messageId}`;
    if (!this.inboundInFlight.get(key)?.changes?.pending) return;
    return (async () => {
      let pending: Promise<void> | undefined;
      while ((pending = this.inboundInFlight.get(key)?.changes?.pending)) await pending;
    })();
  }

  /** Queue a message-scoped mutation. A failed operation is isolated so later events still run. */
  enqueueMessageMutation(id: string, messageId: string, work: () => Promise<void>): void {
    this.mutationProjector.enqueueMessageMutation(id, messageId, work);
  }

  /** Stored-row update for a REST outbound edit, on the same mutation chain — see MessageMutationProjector. */
  recordOutboundMessageEdit(
    sessionId: string,
    messageId: string,
    body: string,
    source?: MutationSource,
  ): Promise<void> {
    let stored: Promise<void> | undefined;
    const pending = this.changeInFlight(sessionId, messageId, source, (needsRow, entry) => {
      if (entry && !needsRow) {
        this.holdEdit(entry, body);
        entry.edited = true;
      }
      stored = this.mutationProjector.recordOutboundMessageEdit(sessionId, messageId, body, source);
    });
    return Promise.resolve(pending).then(() => stored);
  }

  /**
   * Dispatches the opt-in `status.received` webhook once an inbound status row is ingested, and
   * mirrors it over the websocket so the dashboard's statuses view refreshes live instead of
   * waiting for a focus refetch. `WebhookService.dispatch` already filters delivery to webhooks
   * whose `events` array includes `status.received`, so no extra gating is needed here. No media
   * bytes are included in the payload — consumers fetch media via the status media endpoint.
   */
  private dispatchStatusReceived(sessionId: string, row: StatusUpdate): void {
    const payload = {
      sessionId,
      statusId: row.waStatusId,
      contact: {
        id: row.contactJid,
        ...(row.contactName ? { name: row.contactName } : {}),
        ...(row.contactPushName ? { pushName: row.contactPushName } : {}),
      },
      type: row.type,
      ...(row.caption ? { caption: row.caption } : {}),
      hasMedia: Boolean(row.mediaPath) && !row.mediaOmitted,
      mediaOmitted: row.mediaOmitted,
      ...(row.omitReason ? { omitReason: row.omitReason } : {}),
      postedAt: row.postedAt,
      expiresAt: row.expiresAt,
    };
    void this.webhookService.dispatch(sessionId, 'status.received', payload);
    this.eventsGateway.emitStatusReceived(sessionId, payload);
  }
}