Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

64.6 KB
Raw Blame
import { BadRequestException, ConflictException, Injectable, Optional } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { DataSource, QueryRunner } from 'typeorm';
import { InjectDataSource } from '@nestjs/typeorm';
import { createLogger } from '../../common/services/logger.service';
import { isMissingTableError } from '../../common/utils/db-errors';
import { closeSessionWrites } from '../../common/utils/session-write-scope';
import { awaitNoOpenTransaction, SHARED_CONNECTION_DIALECTS } from '../../common/utils/shared-connection';
import { failUnfinishedSessionBatches } from '../message/batch-media.util';
import { AuditService } from '../audit/audit.service';
import { AuditAction } from '../audit/entities/audit-log.entity';
import { SessionService } from '../session/session.service';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { ChatStateStoreService } from '../../engine/adapters/baileys-chat-state-store.service';
import { SessionOwnershipService } from '../session/session-ownership.service';
import { ScopeBindingService } from '../integration/scope-binding.service';
import { ReKeyChatStatesBySessionId1786500000000 } from '../../database/migrations/1786500000000-ReKeyChatStatesBySessionId';
import { ScrubRevokedMessageContent1786900000000 } from '../../database/migrations/1786900000000-ScrubRevokedMessageContent';
import { ScrubNonPhoneLidMappings1786950000000 } from '../../database/migrations/1786950000000-ScrubNonPhoneLidMappings';
import { BackfillLegacyMessageTypes1791300000000 } from '../../database/migrations/1791300000000-BackfillLegacyMessageTypes';
import { Session as SessionEntity, SessionStatus } from '../session/entities/session.entity';
import { In } from 'typeorm';
import { DateUtils } from 'typeorm/util/DateUtils';
import type { MigrationTables, TableCounts } from './migration-tables.types';
import { EXPORT_TABLES, EXPORT_TABLE_EXCLUSIONS, type AnyExportTable } from './export-tables';
import { TABLE_IMPORTERS, deduplicateArchivedWebhookFailures } from './table-importers';

/**
 * The ownership quartet SessionOwnershipService maintains: which process holds a session's engine and
 * until when. Cluster RUNTIME state — it belongs to the machines currently running, never to a backup.
 */
export interface SessionOwnershipRow {
  id: string;
  nodeId: string | null;
  claimedAt: unknown;
  leaseExpiresAt: unknown;
  nodeUrl: string | null;
}

/**
 * Read the live claims through the caller's queryRunner, so the read sits inside the import's own
 * transaction. The columns are PROBED rather than SELECTed-and-caught: on PostgreSQL any failed
 * statement aborts the surrounding transaction (25P02), so catching a missing-column error would
 * still poison every statement after it — including the DELETE this read precedes. Absent columns
 * mean a database whose ownership migration was rolled back; there is simply nothing to carry.
 */
async function readSessionOwnership(queryRunner: QueryRunner): Promise<SessionOwnershipRow[] | null> {
  if (!(await queryRunner.hasColumn('sessions', 'nodeId'))) return null;
  return (await queryRunner.query(
    'SELECT id, "nodeId", "claimedAt", "leaseExpiresAt", "nodeUrl" FROM sessions WHERE "nodeId" IS NOT NULL',
  )) as SessionOwnershipRow[];
}

/**
 * Carry a lease across the transaction by its REMAINING time rather than its absolute stamp.
 *
 * The stamp is a deadline, and the transaction that re-applies it can run for longer than the
 * deadline has left. Writing it back unchanged therefore commits an expiry this request already knows
 * has passed, while `nodeId` still names the owner whose engine never stopped — a lapse manufactured
 * by the restore, on a claim it observed live moments earlier.
 *
 * A claim that was ALREADY lapsed when read is re-bound untouched: shifting that one would resurrect
 * a dead node's hold, which is the property the verbatim write was protecting. So is anything
 * unparseable — a value this function does not understand is not one it should rewrite.
 *
 * The stored shape is preserved (ISO text on SQLite, Date on Postgres) because these values go back
 * through raw SQL, bypassing the column transformer that would otherwise normalise them.
 *
 * Note the deliberate asymmetry with `claimedAt`, which stays verbatim because it is a historical
 * fact. After a carry the pair therefore no longer spans a single TTL — `leaseExpiresAt - claimedAt`
 * is the TTL plus the restore's duration — so it must not be used to derive a lease age.
 */
function carryLease(raw: unknown, readAt: Date, now: Date): unknown {
  // Only the two shapes these columns are actually stored in are interpreted, and for text only the
  // UTC form the two writers emit (`DateTransformer.to` and `leaseParam`, both `toISOString()`).
  // Anything else is left alone: rewriting a shape this function does not understand would be worse
  // than not carrying it, because a local-time parse would bake the host's UTC offset into the
  // column permanently — where the old verbatim write merely passed the odd value through.
  if (!(raw instanceof Date) && typeof raw !== 'string') return raw;
  if (typeof raw === 'string' && !raw.endsWith('Z')) return raw;
  const deadline = raw instanceof Date ? raw : new Date(raw);
  const remainingMs = deadline.getTime() - readAt.getTime();
  if (Number.isNaN(remainingMs) || remainingMs <= 0) return raw;
  // Never earlier than what was read: a backward clock step between the two stamps must not be able
  // to commit an expiry sooner than the row already carried, which would re-create the very problem.
  const carried = new Date(Math.max(now.getTime() + remainingMs, deadline.getTime()));
  // A deadline that is representable but whose carry is not: fall back rather than throw, since the
  // caller routes a throw into `warnings` and every later row in the loop would lose its claim.
  if (!Number.isFinite(carried.getTime())) return raw;
  return raw instanceof Date ? carried : carried.toISOString();
}

/**
 * Re-apply the claims for ids present in both the pre-import database and the restored set.
 * `nodeId`/`claimedAt`/`nodeUrl` are re-bound exactly as they were read rather than reconstructed;
 * only the lease deadline is carried forward (see {@link carryLease}). They go through the caller's
 * `insert` so the `$N`→`?` rewrite applies on SQLite. An id the backup did not restore simply
 * matches no row.
 *
 * Errors are NOT swallowed. On PostgreSQL a failed statement aborts the transaction, and the COMMIT
 * that followed would silently execute as a ROLLBACK — reporting a fully-discarded import as a
 * success with per-table counts. The caller routes a failure into `warnings`, which is the existing
 * all-or-nothing gate.
 */
export async function restoreSessionOwnership(
  preserved: SessionOwnershipRow[] | null,
  insert: (text: string, params: unknown[]) => Promise<unknown>,
  readAt: Date,
  now: Date = new Date(),
): Promise<void> {
  if (!preserved?.length) return;
  for (const row of preserved) {
    await insert(
      'UPDATE sessions SET "nodeId" = $1, "claimedAt" = $2, "leaseExpiresAt" = $3, "nodeUrl" = $4 WHERE id = $5',
      [row.nodeId, row.claimedAt, carryLease(row.leaseExpiresAt, readAt, now), row.nodeUrl, row.id],
    );
  }
}

/**
 * The `datetime` columns of each imported table on a SQLite data connection, keyed by backup table key
 * and read from the entity metadata: CreateDateColumn/UpdateDateColumn and any other column TypeORM
 * binds through its SQLite datetime path. DateTransformer columns are `text` there and are not listed,
 * because the app itself writes those in ISO form.
 */
export function sqliteDatetimeColumns(dataSource: DataSource): Map<keyof MigrationTables, string[]> {
  const byTable = new Map(
    dataSource.entityMetadatas.map(metadata => [
      metadata.tableName,
      metadata.columns
        .filter(column => dataSource.driver.normalizeType(column) === 'datetime')
        .map(column => column.databaseName),
    ]),
  );
  return new Map(EXPORT_TABLES.map(entry => [entry.key, byTable.get(entry.table) ?? []]));
}

/**
 * Rewrite one archived `datetime` value into the text TypeORM writes on SQLite (`YYYY-MM-DD HH:MM:SS.SSS`,
 * UTC). A PostgreSQL export serializes these columns as ISO `...T...Z`, and SQLite compares them as
 * text: `'T'` sorts after `' '`, so a restored row never matches `LessThan(date)` on its own calendar
 * day. Only ISO text with an explicit zone is converted. A value already in SQLite form carries no
 * zone, and parsing it would read it as host-local time and shift it, so it is left as it is.
 */
export function toSqliteDatetime(value: unknown): unknown {
  if (typeof value !== 'string' || !/T.*(Z|[+-]\d{2}:?\d{2})$/i.test(value)) return value;
  const date = new Date(value);
  return Number.isNaN(date.getTime()) ? value : DateUtils.mixedDateToUtcDatetimeString(date);
}

/**
 * Aggregate budget for the inline base64 media ONE export may carry, counted in the encoded bytes
 * that actually land in the JSON body. Override with EXPORT_INLINE_MEDIA_BUDGET_BYTES; 0 omits every
 * payload, and anything that is not a non-negative decimal integer falls back to the default.
 *
 * The export is bounded by nothing while the import rides the global request body limit (25mb by
 * default, `resolveBodyLimit`), so unbounded inline media produces a backup this gateway then refuses
 * with a 413 — inbound media is capped at MEDIA_DOWNLOAD_MAX_BYTES (50 MiB by default) and base64
 * inflates that to 4/3.
 *
 * A blanket strip would trade the 413 for silent data loss, which is why this is a budget and not a
 * flag: with the chat-media archive off — the default — `metadata.media.data` is the ONLY copy of an
 * inbound photo, and a 180 KB one costs nothing against a 25 MiB ceiling. Mirrors
 * CHAT_HISTORY_MEDIA_BUDGET_BYTES, which bounds the same failure on the chat-history response.
 */
const DEFAULT_EXPORT_INLINE_MEDIA_BUDGET_BYTES = 8 * 1024 * 1024;

function exportInlineMediaBudgetBytes(): number {
  const parsed = Number.parseInt(process.env.EXPORT_INLINE_MEDIA_BUDGET_BYTES ?? '', 10);
  return Number.isInteger(parsed) && parsed >= 0 ? parsed : DEFAULT_EXPORT_INLINE_MEDIA_BUDGET_BYTES;
}

/**
 * Order rows so the media budget is spent newest-first, keeping the most recent media when it cannot
 * hold everything. `SELECT *` carries no ORDER BY: rows arrive in rowid order on SQLite — oldest
 * first, the exact inverse of what a backup wants — and in physical-tuple order on Postgres, which
 * routine UPDATEs reshuffle, so two exports of an unchanged DB need not agree. Sorts a COPY, leaving
 * the exported array's own order untouched. A row with no usable timestamp sorts last, as the least
 * worth spending the budget on.
 */
function newestFirst<T>(rows: readonly T[], at: (row: T) => number): T[] {
  const key = (row: T): number => {
    const value = at(row);
    return Number.isFinite(value) ? value : 0;
  };
  return [...rows].sort((a, b) => key(b) - key(a));
}

/**
 * A chunk of full-row reads from an inline-media table holds at most max(budget, 1 MiB) of stored
 * payload (and always at least one row), as the message list does. The row cap keeps a chunk of
 * small rows well inside every driver's bound-parameter limit.
 */
const EXPORT_READ_CHUNK_MIN_BYTES = 1024 * 1024;
const EXPORT_READ_CHUNK_MAX_ROWS = 200;

/**
 * Spends the shared budget, and remembers what it refused.
 *
 * `exceeds` returns true when this payload does not fit and must be dropped. The tally matters as
 * much as the bound: an over-budget payload is replaced with the engine's own omitted marker, which
 * is deliberately the same shape a payload skipped on the way in gets — so without a count, a
 * truncated backup is indistinguishable from a complete one, both on inspection and on restore.
 */
interface InlineMediaBudget {
  /** The configured budget, which also sizes the export's chunked reads. */
  bytes: number;
  exceeds: (encodedBytes: number) => boolean;
  droppedPayloads: () => number;
}

function createInlineMediaBudget(): InlineMediaBudget {
  const budget = exportInlineMediaBudgetBytes();
  let spent = 0;
  let dropped = 0;
  return {
    bytes: budget,
    exceeds: (encodedBytes: number): boolean => {
      if (spent + encodedBytes > budget) {
        dropped += 1;
        return true;
      }
      spent += encodedBytes;
      return false;
    },
    droppedPayloads: () => dropped,
  };
}

/** Result of GET /infra/export-data; InfraExportDataResponseDto is the published contract. */
export interface InfraExportDataResult {
  exportedAt: string;
  dataDbType: string;
  tables: MigrationTables;
  counts: TableCounts;
  /** Optional tables that were skipped because they genuinely do not exist in this DB (older schema). */
  skippedTables: string[];
  /**
   * Inline media payloads the export budget refused, so a truncated backup can be told apart from
   * a complete one. Zeroes mean everything fitted. Restoring an archive with a non-zero count is
   * still valid — the rows come back, their media does not.
   */
  omittedInlineMedia: { messages: number; messageBatches: number };
}

const EMPTY_ARCHIVE_WARNING = 'Backup contained no rows to restore; refused to replace existing data. Check the file.';

/** Result of POST /infra/import-data; InfraImportDataResponseDto is the published contract. */
export interface InfraImportDataResult {
  imported: boolean;
  counts: TableCounts;
  warnings: string[];
  /**
   * Non-fatal operator-facing messages (e.g. orphan-engine reconciliation details). Distinct from
   * warnings: notices never cause a rollback, while warnings make the replace-rollback gate fire.
   */
  notices: string[];
  /**
   * True when an engine may still be writing into the restored tables, from any of three causes:
   * orphans deliberately left running (`force`), a `stopOrphans` teardown that failed, or sessions
   * held by another node, which this request has no channel to stop. Restart to reconcile those.
   * Also true when the post-commit plugin binding re-sync failed; a restart does not repair that
   * one, so its notice names the manual check instead.
   */
  restartRequired: boolean;
  /** Session ids with a running engine that the restored data no longer contains. */
  orphanedEngines: string[];
  /** Orphan engines stopped inside this request (only populated when stopOrphans=true was passed). */
  stoppedOrphanEngines: string[];
  /** Orphan engines whose teardown threw or timed out (Map reconciled regardless; investigate). */
  failedOrphanEngines: string[];
}

/**
 * The data-DB backup machinery behind InfraDataController: the full export (registry-driven, see
 * export-tables.ts) and the replace-all import with its single-flight gate, orphan-engine
 * reconciliation and all-or-nothing rollback. The controller owns only routing, guards and the
 * published response metadata.
 */
@Injectable()
export class InfraDataService {
  private readonly logger = createLogger('InfraDataService');

  /**
   * Whether a replace-all import is already running in this process. Not a nicety: on better-sqlite3
   * every query runner is a driver SINGLETON, so two overlapping imports share one transaction — the
   * second nests as SAVEPOINT, its commit issues RELEASE SAVEPOINT rather than COMMIT, and a rollback
   * at depth 1 issues a full ROLLBACK that discards a restore the other call already answered
   * `imported: true` for. Serialising them is the only honest answer; queueing the second would still
   * run a destructive replace nobody is waiting on.
   */
  private importInFlight = false;

  /**
   * Exports running in this process. On better-sqlite3 an export's reads share the import's connection,
   * so an export and an import that overlap would archive the import's uncommitted (possibly rolled-back)
   * tables. Each refuses while the other runs.
   */
  private exportsInFlight = 0;

  constructor(
    private readonly configService: ConfigService,
    @InjectDataSource('data')
    private readonly dataDataSource: DataSource,
    // Best-effort audit emission for the sensitive infra operations below. Injected @Optional and
    // grouped with the trailing @Optional args so it never shifts the required positional args: the
    // running app always provides the @Global AuditService, while the direct-construction unit tests
    // omit it — the `?.` at each call site then makes emission a no-op there instead of forcing
    // every test to wire a mock.
    @Optional()
    private readonly auditService?: AuditService,
    // Post-import runtime reconciliation (see importData). Same trailing-@Optional convention as
    // auditService: provided by the app (InfraModule imports SessionModule; EngineModule is @Global),
    // omitted by direct-construction unit tests, and every use is `?.`-guarded.
    @Optional()
    private readonly sessionService?: SessionService,
    @Optional()
    private readonly lidMappingStore?: LidMappingStoreService,
    // Same trailing-@Optional convention as the services above: provided by the app, omitted by the
    // direct-construction unit tests, and every use is `?.`-guarded.
    @Optional()
    private readonly ownership?: SessionOwnershipService,
    @Optional()
    private readonly chatStateStore?: ChatStateStoreService,
    // Resolves ScopeBindingService lazily (strict: false) for the post-import plugin binding resync.
    // A lookup rather than a module import: importing IntegrationModule here would move it deeper in
    // the module graph and reorder its lifecycle hooks relative to the rest of the app.
    @Optional()
    private readonly moduleRef?: ModuleRef,
  ) {}

  /**
   * Fail loudly when EXPORT_TABLES and the data connection's entity metadata disagree, BEFORE a
   * single table is read. A registry table the metadata does not know means a renamed or dropped
   * entity: proceeding would export the OLD table (or report it empty/skipped) and a restore would
   * re-populate a table nothing reads. A metadata table in neither the registry nor the exclusions
   * means a new entity nobody made a backup decision for: proceeding would silently leave it out of
   * every backup this gateway produces. Both are registry drift, not data conditions — the operator
   * cannot fix them from a request.
   */
  private assertExportRegistryMatchesMetadata(): void {
    const metadataTables = new Set(this.dataDataSource.entityMetadatas.map(metadata => metadata.tableName));
    for (const entry of EXPORT_TABLES) {
      if (!metadataTables.has(entry.table)) {
        throw new Error(
          `export-data: table "${entry.table}" (backup key "${entry.key}") is registered for export, but the ` +
            `data connection's entity metadata does not know it — a renamed or dropped entity must be ` +
            `updated in export-tables.ts, never exported around`,
        );
      }
    }
    const registryTables = new Set(EXPORT_TABLES.map(entry => entry.table));
    for (const table of metadataTables) {
      if (registryTables.has(table) || table in EXPORT_TABLE_EXCLUSIONS) continue;
      throw new Error(
        `export-data: data entity table "${table}" has no backup decision — add it to EXPORT_TABLES (with its ` +
          `import descriptor and the published tables/counts DTO keys) or to EXPORT_TABLE_EXCLUSIONS with a ` +
          `reason, in export-tables.ts`,
      );
    }
  }

  async exportData(): Promise<InfraExportDataResult> {
    this.assertExportRegistryMatchesMetadata();
    if (this.importInFlight) {
      throw new ConflictException({
        statusCode: 409,
        error: 'Conflict',
        message: 'A data import is running; export after it finishes.',
        code: 'IMPORT_ALREADY_RUNNING',
      });
    }
    this.exportsInFlight++;
    try {
      return await this.runExport();
    } finally {
      this.exportsInFlight--;
    }
  }

  /** The table reads behind exportData, entered only through its import guard. */
  private async runExport(): Promise<InfraExportDataResult> {
    // The tables below may legitimately not exist yet (created by migrations an older DB has not run).
    // Only a GENUINE missing-table error (isMissingTableError) may be tolerated — anything else (lock,
    // I/O, timeout, aborted connection) must FAIL the export. The old blind `catch { debug-log }`
    // pattern reported those as "table is empty", producing a 200 "complete" backup that was actually
    // partial — which the import then treated as authoritative and DELETEd the missing tables' rows.
    // A skipped table is surfaced in `skippedTables` (and logged as a warning) so an operator can tell
    // "not migrated yet" apart from "exported empty".
    const skippedTables: string[] = [];
    const readTable = async (entry: AnyExportTable, sql: string): Promise<unknown[]> => {
      try {
        return await this.dataDataSource.query(sql);
      } catch (error) {
        if (!entry.optional || !isMissingTableError(error)) throw error;
        skippedTables.push(entry.table);
        this.logger.warn('Optional table does not exist in this DB; exporting without it', { table: entry.table });
        return [];
      }
    };

    // One budget shared by the tables that carry a full inline payload (messages and
    // message_batches today), so the total is what is bounded rather than each table separately.
    const inlineMediaBudget = createInlineMediaBudget();
    // The per-bucket drop counts are measured as the delta around each budgeted table's read, which
    // attributes every refusal to the table that spent it and keeps the snapshot semantics the
    // response documents: messages are served first, batches spend what is left.
    const droppedByBucket: Record<'messages' | 'messageBatches', number> = { messages: 0, messageBatches: 0 };
    const tables = {} as MigrationTables;
    const counts = {} as TableCounts;

    for (const entry of EXPORT_TABLES) {
      const droppedBefore = inlineMediaBudget.droppedPayloads();
      const rows: unknown[] = entry.inlineMedia
        ? await this.readInlineMediaTable(entry, entry.inlineMedia, sql => readTable(entry, sql), inlineMediaBudget)
        : await readTable(
            entry,
            `SELECT ${entry.columns?.map(column => `"${column}"`).join(', ') ?? '*'} FROM ${entry.table}`,
          );
      // `rows` was read for exactly this entry's table, so it holds the row type the entry's hooks
      // declare. That correlation is what the erased entry type cannot carry, and this loop is the
      // one place it is known — so the casts live here rather than at each hook.
      entry.afterRead?.(rows as never[]);
      if (entry.inlineMedia) {
        droppedByBucket[entry.inlineMedia.bucket] = inlineMediaBudget.droppedPayloads() - droppedBefore;
      }
      tables[entry.key] = rows as never;
      counts[entry.key] = rows.length;
    }

    // See ExportTable.sessionFk: a child row of a session missing from the archive cannot be restored.
    const exportedSessions = new Set(tables.sessions.map(session => session.id));
    for (const entry of EXPORT_TABLES) {
      if (!entry.sessionFk) continue;
      const kept = (tables[entry.key] as Array<{ sessionId: string }>).filter(row =>
        exportedSessions.has(row.sessionId),
      );
      tables[entry.key] = kept as never;
      counts[entry.key] = kept.length;
    }

    // Audit the full-DB export: this payload carries plugin-instance secrets, so WHO pulled
    // a dump (and the per-table row counts) must land in the audit log. Data itself is never
    // logged — only counts.
    await this.auditService?.logInfo(AuditAction.INFRA_DATA_EXPORTED, { metadata: { counts } });

    return {
      exportedAt: new Date().toISOString(),
      dataDbType: this.configService.get<string>('dataDatabase.type', 'sqlite'),
      tables,
      counts,
      skippedTables,
      omittedInlineMedia: droppedByBucket,
    };
  }

  /**
   * Read a table whose rows carry inline media without ever holding all of its payloads at once.
   *
   * A `SELECT *` put every payload on the heap before the budget could drop one, so a media-heavy
   * database could exhaust memory for a response that only ever carries the budget's worth. Instead
   * every row is read as `id`, its recency key and its payload's stored size; the full rows follow
   * newest-first in chunks, and each chunk is stripped against the budget before the next is read.
   * Peak memory is the stripped rows, one chunk and the budget.
   *
   * The budget sees the rows in exactly the order `newestFirst` gave it over a `SELECT *`, and the
   * result keeps the key read's row order, which is the order `SELECT *` returned; the caller applies
   * `afterRead` to it as to any other table. A row deleted between the key read and its chunk is left
   * out; one inserted after the key read is not exported.
   */
  private async readInlineMediaTable(
    entry: AnyExportTable,
    media: NonNullable<AnyExportTable['inlineMedia']>,
    readKeys: (sql: string) => Promise<unknown[]>,
    budget: InlineMediaBudget,
  ): Promise<unknown[]> {
    const keys = (await readKeys(
      `SELECT id, "${media.recencyColumn}", OCTET_LENGTH("${media.payloadColumn}") AS "payloadBytes" FROM ${entry.table}`,
    )) as Array<{ id: unknown; payloadBytes: number | string | null }>;
    const chunkLimit = Math.max(budget.bytes, EXPORT_READ_CHUNK_MIN_BYTES);
    const stripped = new Map<unknown, unknown>();
    let chunk: unknown[] = [];
    let chunkBytes = 0;

    const flush = async (): Promise<void> => {
      const isPostgres = this.dataDataSource.options.type === 'postgres';
      const placeholders = chunk.map((_, i) => (isPostgres ? `$${i + 1}` : '?')).join(', ');
      const rows = await this.dataDataSource.query<Array<{ id: unknown }>>(
        `SELECT * FROM ${entry.table} WHERE id IN (${placeholders})`,
        chunk,
      );
      // IN returns the rows in no particular order; the budget is spent in the chunk's own order.
      const byId = new Map(rows.map(row => [row.id, row]));
      for (const id of chunk) {
        const row = byId.get(id);
        if (!row) continue;
        media.strip(row as never, budget.exceeds);
        stripped.set(id, row);
      }
      chunk = [];
      chunkBytes = 0;
    };

    for (const key of newestFirst(keys, media.newestFirst as (row: unknown) => number)) {
      const bytes = Number(key.payloadBytes) || 0;
      const full = chunk.length === EXPORT_READ_CHUNK_MAX_ROWS || chunkBytes + bytes > chunkLimit;
      if (chunk.length > 0 && full) await flush();
      chunk.push(key.id);
      chunkBytes += bytes;
    }
    if (chunk.length > 0) await flush();
    return keys.filter(key => stripped.has(key.id)).map(key => stripped.get(key.id));
  }

  async importData(data: {
    tables: Partial<MigrationTables>;
    force?: boolean;
    stopOrphans?: boolean;
  }): Promise<InfraImportDataResult> {
    // Check-and-set with NO await between them, so the single-threaded event loop makes this atomic:
    // the first call reaches the assignment before the second call starts. It guards the whole method,
    // including the pre-flight orphan teardown below — running that twice concurrently would stop
    // engines on behalf of a restore that is about to be refused.
    if (this.importInFlight) {
      throw new ConflictException({
        statusCode: 409,
        error: 'Conflict',
        message: 'A data import is already running; wait for it to finish before starting another.',
        code: 'IMPORT_ALREADY_RUNNING',
      });
    }
    if (this.exportsInFlight > 0) {
      throw new ConflictException({
        statusCode: 409,
        error: 'Conflict',
        message: 'A data export is running; import after it finishes.',
        code: 'EXPORT_IN_PROGRESS',
      });
    }
    this.importInFlight = true;
    try {
      return await this.runImport(data);
    } finally {
      this.importInFlight = false;
    }
  }

  /** The replace-all restore itself. Only ever entered through importData's single-flight guard. */
  private async runImport(data: {
    tables: Partial<MigrationTables>;
    force?: boolean;
    stopOrphans?: boolean;
  }): Promise<InfraImportDataResult> {
    const warnings: string[] = [];

    // Runtime reconciliation, part 1 (pre-flight): the replace below DELETES every session not in the
    // backup, but an engine started for such a session keeps running as an unstoppable zombie (the
    // session service keys engines by session id, and every stop path goes through the now-missing DB
    // row) whose inbound messages land in tables that were just replaced. Three operator-chosen paths:
    //   - default: refuse with 409 listing the orphan ids;
    //   - force=true: proceed and leave the engines running until process restart (restartRequired=true);
    //   - stopOrphans=true: stop each orphan engine inside this request (best-effort, time-bounded,
    //     isolated per engine) and then proceed — restartRequired stays false on the success path.
    // stopOrphans is preferred over force for the orphan case: a force restore that silently leaves
    // engines writing into the freshly replaced tables for an unbounded time is the corruption this
    // gate exists to prevent, so the explicit-stop path closes that window instead of relying on the
    // operator to restart promptly.
    // Every present table must be an array of rows before anything dereferences one. `.map()` on a
    // string or a number is a TypeError — a 500 telling the operator the SERVER broke, when their
    // archive is simply malformed. Checked for all tables, not just `sessions`: the rest are read
    // inside the transaction, where the same mistake would fail mid-restore instead of before it.
    for (const [table, rows] of Object.entries(data.tables ?? {})) {
      if (rows === undefined) continue;
      if (!Array.isArray(rows)) {
        throw new BadRequestException(`tables.${table} must be an array of rows`);
      }
      // Array.isArray alone is not enough: `[null]` passes it and then dies on the first property
      // read, which is the same 500 with a longer fuse. Every element must be a row object.
      const badRow = rows.findIndex(row => typeof row !== 'object' || row === null || Array.isArray(row));
      if (badRow !== -1) {
        throw new BadRequestException(`tables.${table}[${badRow}] must be a row object`);
      }
    }

    // An archive with no rows is always refused (see the totalRestored check below), so refuse it here,
    // before the orphan pre-flight: with no sessions in it every running engine reads as an orphan, and
    // a stopOrphans retry would tear all of them down for a restore that was never going to happen.
    // A row a skip guard vetoes is just as certain a rollback (see the warnings gate below), and the
    // guards read only the archived tables, so run them here too. The in-transaction call stays as a backstop.
    const refusals = TABLE_IMPORTERS.every(importer => !data.tables[importer.key]?.length)
      ? [EMPTY_ARCHIVE_WARNING]
      : TABLE_IMPORTERS.flatMap(importer =>
          (data.tables[importer.key] ?? [])
            .map((row, _index, rows) => importer.skip?.(row as never, rows as never))
            .filter((warning): warning is string => warning != null),
        );
    if (refusals.length > 0) {
      return {
        imported: false,
        counts: Object.fromEntries(TABLE_IMPORTERS.map(importer => [importer.key, 0] as const)) as TableCounts,
        warnings: refusals,
        notices: [],
        restartRequired: false,
        orphanedEngines: [],
        stoppedOrphanEngines: [],
        failedOrphanEngines: [],
      };
    }

    const importedSessionIds = new Set((data.tables.sessions ?? []).map(s => s.id));
    const orphanedEngines = (this.sessionService?.getActiveSessionIds() ?? []).filter(
      id => !importedSessionIds.has(id),
    );

    let stoppedOrphanEngines: string[] = [];
    let failedOrphanEngines: string[] = [];
    let restartRequired = false;

    // notices collect non-fatal operator-facing messages (orphan-engine reconciliation details) that
    // must NOT trip the warnings→rollback gate further down. warnings is reserved for per-row import
    // failures that make the replace partial and therefore require a rollback.
    const notices: string[] = [];

    // `getActiveSessionIds` reads this process's own engine registry, so an engine another node is
    // running is invisible here and cannot be stopped from this request — there is no cross-process
    // control channel. Left unsaid, a clean response would read as "every orphan was reconciled".
    // Say it instead: the operator is the only one who can act on it.
    const heldElsewhere = (await this.ownership?.heldByOtherNodes()) ?? [];
    if (heldElsewhere.length > 0) {
      restartRequired = true;
      notices.push(
        `${heldElsewhere.length} session(s) are running on another node and could not be reconciled from ` +
          `this request: ${heldElsewhere.join(', ')}. Their engines may still write into the restored ` +
          `tables — stop those nodes before relying on this import.`,
      );
    }

    if (orphanedEngines.length > 0 && data.stopOrphans && this.sessionService) {
      // Stop the orphans inside this request, BEFORE the transaction opens. Two 10s deadlines per
      // engine (destroy, then forceDestroy), run in parallel, bound the worst case (a stuck Chromium
      // cannot wedge the import); the engines are reconciled from the Map regardless of teardown outcome.
      const result = await this.sessionService.stopOrphanEngines(orphanedEngines);
      stoppedOrphanEngines = result.stopped;
      failedOrphanEngines = result.failed;
      // The teardown cannot be rolled back, and the import's own audit row is written only for a committed
      // restore, so each stopped session is recorded here: a refused or failed restore would leave no trace.
      for (const sessionId of result.stopped) {
        await this.auditService?.logInfo(AuditAction.SESSION_STOPPED, {
          sessionId,
          metadata: { via: 'infra_import_data' },
        });
      }
      if (failedOrphanEngines.length > 0) {
        // Teardown failed for at least one orphan. The Map entry is removed regardless (see
        // stopOrphanEngines), so the engine no longer holds a concurrency slot — but its underlying
        // Chromium/socket may still be alive and writing into restored tables. Surface the ids and
        // flag restartRequired so the operator does not read a clean response as "engines stopped".
        restartRequired = true;
        notices.push(
          `Teardown failed for ${failedOrphanEngines.length} orphan engine(s): ${failedOrphanEngines.join(', ')} ` +
            `(removed from the engine registry; a process restart guarantees cleanup).`,
        );
      }
      // Sessions with no engine yet are reported in notRunning: one still initializing aborts its start()
      // on the stop mark, and one waiting to relaunch after a failed reconnect had its relaunch cancelled.
      // Neither is counted as stopped here.
      if (result.notRunning.length > 0) {
        notices.push(
          `${result.notRunning.length} orphan session(s) had no live engine yet (initializing or waiting to ` +
            `reconnect): ${result.notRunning.join(', ')}; they will not start.`,
        );
      }
    } else if (orphanedEngines.length > 0 && !data.force) {
      // Carries a code like the other two refusals, and for a stronger reason: this is the ONLY 409
      // on this route whose documented retry (stopOrphans=true) is destructive — it stops live
      // engines — and dashboard/src/utils/importRefusal.ts decides whether to offer that retry by
      // matching this code. Renaming it there and here together is required; renaming it here alone
      // leaves both suites green and withdraws the operator's only route to stopOrphans. Were the
      // case identified by the ABSENCE of a code instead, every unrecognised 409 (a proxy's, a body
      // that never parsed) would open a confirm whose OK tears down engines and replaces every table.
      throw new ConflictException({
        statusCode: 409,
        error: 'Conflict',
        message:
          `Import would orphan ${orphanedEngines.length} running engine(s) for session(s) ` +
          `${orphanedEngines.join(', ')} that the backup does not contain. Stop them first, retry with ` +
          `stopOrphans=true (stops them inside this request), or retry with force=true ` +
          `(a server restart is then required to stop the orphaned engines).`,
        code: 'IMPORT_WOULD_ORPHAN_ENGINES',
      });
    } else if (orphanedEngines.length > 0 && data.force) {
      // Legacy escape hatch: proceed and leave the engines running until restart.
      restartRequired = true;
    }

    // What the rollback branches below must report about the engines. The transaction can be rolled
    // back; the orphan teardown above CANNOT — it ran before the transaction opened and those engines
    // are already destroyed. Reporting empty arrays there would tell an operator nothing happened
    // while their sessions are down.
    //
    // restartRequired narrows to the one thing a rollback cannot undo: a FAILED teardown may have left
    // a Chromium/socket alive. The two other pre-flight outcomes do not survive the rollback as
    // restart-worthy — a cleanly stopped orphan leaves its session row intact (restart it through
    // POST /sessions/:id/start), and an engine the force path left running was never orphaned after
    // all, because the data it would have been orphaned by is gone.
    const engineStateAfterRollback = {
      restartRequired: failedOrphanEngines.length > 0,
      orphanedEngines,
      stoppedOrphanEngines,
      failedOrphanEngines,
    };

    // Silence the ownership heartbeat's loss detection for the whole transaction — but ONLY where the
    // hazard exists. On SQLite every query runner shares one connection, so a heartbeat tick executes
    // INSIDE this transaction, after the DELETE below and before the re-inserts commit, and sees no
    // session rows at all; it would read that as "a peer took everything" and tear down every engine
    // on this node, even on the paths where this import then rolls back. Postgres hands each runner a
    // dedicated pooled client, so the heartbeat cannot see any of it — suspending there would only
    // disable genuine loss detection in the multi-node deployment that depends on it.
    const sharesOneConnection = SHARED_CONNECTION_DIALECTS.has(this.dataDataSource.options.type);
    const resumeLossDetection = sharesOneConnection ? this.ownership?.suspendLossDetection() : undefined;

    // The replace deletes every session the archive does not hold, rows and all, and messages has no foreign
    // key to refuse a send or batch row that lands after it. So their write scopes are closed and drained
    // before the transaction opens, as SessionEngineControls.delete does. Not for an engine force left
    // running, which keeps writing (restartRequired says so), nor for one another node holds.
    const leftRunning = new Set([...heldElsewhere, ...(data.stopOrphans ? [] : orphanedEngines)]);
    let retired: Array<{ id: string; writes: ReturnType<typeof closeSessionWrites> }> = [];
    let committed = false;
    // Set when another transaction opened on the shared connection while the writes drained.
    let foreignTransaction = false;

    // Everything from here is wrapped so the token cannot outlive this request. It is not enough to
    // release it in the transaction's own finally: createQueryRunner/connect/startTransaction sit
    // before that finally exists, so any throw there — a driver change, a broadcaster subscriber, a
    // failing BEGIN/SAVEPOINT — would strand it. Defence in depth rather than a reachable bug today,
    // and deliberately so: a leaked token disables loss detection for the lifetime of the process,
    // silently, which is strictly worse than the teardown the suspension prevents.
    try {
      const queryRunner = this.dataDataSource.createQueryRunner();

      // Refuse BEFORE a single row is deleted, not after. On better-sqlite3 every query runner is a
      // driver SINGLETON, so if anything else already holds a transaction on this DataSource — a
      // session create or delete — this import would not get its own: it would become a SAVEPOINT
      // inside theirs, and commitTransaction() would issue RELEASE SAVEPOINT rather than COMMIT.
      //
      // The outcome of that is genuinely indeterminate, which is why detecting it afterwards is not
      // good enough: if the enclosing transaction commits, the replace lands; if it rolls back, the
      // replace vanishes. Either way this request cannot report the truth, and it has already
      // deleted every row — including any the enclosing transaction just wrote. Refusing up front is
      // the only answer that is both honest and non-destructive. On Postgres each runner gets its own
      // pooled client, so this is always false there and the check costs nothing.
      //
      // The try/finally that releases the runner opens only after BEGIN, so the refusal and a failing
      // BEGIN give the runner back here: a pooled PostgreSQL client would otherwise stay checked out for
      // the life of the process.
      const refuseNestedTransaction = (): void => {
        if (queryRunner.isTransactionActive) {
          throw new ConflictException({
            statusCode: 409,
            error: 'Conflict',
            message:
              'Another database transaction is in progress on this connection, so a restore could not be ' +
              'made durable. Retry with no other data operation in flight.',
            code: 'IMPORT_NESTED_TRANSACTION',
          });
        }
      };
      try {
        refuseNestedTransaction();
        // Drained before BEGIN: on SQLite a write still in flight would otherwise join this transaction. And
        // before this runner takes a pooled client on PostgreSQL, where the write may still need one: with a
        // pool of one it would wait for the import while the import waits for it. So the ids are read on a
        // client that goes back at once there; on SQLite this runner is the one connection anyway.
        const existing = await this.dataDataSource.query<Array<{ id: string }>>(
          'SELECT id FROM sessions',
          [],
          sharesOneConnection ? queryRunner : undefined,
        );
        retired = existing
          .filter(({ id }) => !importedSessionIds.has(id) && !leftRunning.has(id))
          .map(({ id }) => ({ id, writes: closeSessionWrites(this.dataDataSource, id) }));
        await Promise.all(retired.map(({ writes }) => writes.drain()));
        await queryRunner.connect();
        // Again after the drain's await: BEGIN must follow the check with nothing in between.
        if (queryRunner.isTransactionActive) foreignTransaction = true;
        refuseNestedTransaction();
        await queryRunner.startTransaction();
      } catch (error) {
        await queryRunner.release().catch(() => undefined);
        throw error;
      }

      try {
        const isPostgres = this.dataDataSource.options.type === 'postgres';
        if (isPostgres) {
          // The runtime pool carries a statement_timeout sized for request traffic (30 s by default), but
          // the clears and scrubs below scale with the live tables, not with the archive: restoring an
          // earlier export onto an instance whose messages table has since grown to millions of rows
          // would be cancelled mid-DELETE, after the engines of the sessions it drops were already
          // stopped. Lifted for this transaction only, as the migrations do. A lock wait keeps the bound
          // the statement timeout gave it, so a stuck lock still fails the import instead of hanging it.
          const lockWaitMs = Math.max(
            0,
            Math.trunc(this.configService.get<number>('dataDatabase.statementTimeoutMs', 30000)) || 0,
          );
          await queryRunner.query('SET LOCAL statement_timeout = 0');
          await queryRunner.query(`SET LOCAL lock_timeout = ${lockWaitMs}`);
        }
        // Clear existing data (in correct order due to foreign keys). templates and
        // baileys_stored_messages FK sessions ON DELETE CASCADE, so the sessions DELETE would clear
        // them too; clearing them explicitly first keeps the order correct on engines where the
        // cascade is not enforced. Tolerate a genuinely-absent table (isMissingTableError) but let any
        // OTHER failure (lock, I/O, aborted tx) propagate to the transaction rollback below — a blind
        // `.catch(() => {})` here could otherwise silently commit a MERGED (not replaced) restore on
        // SQLite, violating the endpoint's "replaces existing data" contract.
        const clearTable = async (table: string, where = ''): Promise<void> => {
          // Asked first on PostgreSQL: a statement that names a missing relation aborts the whole transaction even
          // when its error is caught, and every later statement then fails with 25P02.
          if (isPostgres && !(await queryRunner.hasTable(table))) {
            this.logger.debug('Skipped clearing a table that does not exist during import', { table });
            return;
          }
          try {
            await queryRunner.query(`DELETE FROM ${table}${where}`);
          } catch (err) {
            if (isPostgres || !isMissingTableError(err)) throw err;
            this.logger.debug('Skipped clearing a table that does not exist during import', { table });
          }
        };
        // The INSERTs below are written once, in Postgres' `$N` placeholder form. better-sqlite3 differs
        // from the legacy sqlite3 driver on raw queries in two ways: SQLite parses `$N` as a NAMED
        // parameter, which cannot be bound from the positional array TypeORM passes through (RangeError),
        // and strict binding rejects booleans/undefined — which a Postgres-made backup carries (real
        // booleans survive the JSON round-trip). Postgres needs `$N` and binds booleans natively, so both
        // rewrites apply only on the SQLite path. Safe: every `$N` below occurs once, in ascending order.
        const insert = (text: string, params: unknown[]): Promise<unknown> =>
          queryRunner.query(
            isPostgres ? text : text.replace(/\$\d+/g, '?'),
            isPostgres ? params : params.map(v => (typeof v === 'boolean' ? Number(v) : (v ?? null))),
          );
        await queryRunner.query('DELETE FROM webhooks');
        await clearTable('messages');
        await clearTable('message_batches');
        await clearTable('templates');
        await clearTable('baileys_stored_messages');
        // lid_mappings is not a FK to sessions, so the sessions DELETE below won't clear it; clear it
        // explicitly so a restore replaces the cache rather than colliding on existing lid PKs.
        await clearTable('lid_mappings');
        // chat_states is the same case: PK (sessionId, chatId), no FK to sessions, so the sessions DELETE
        // does not reach it. Without this, a restore onto an instance that already holds chat_states rows
        // collides on those PKs and the all-or-nothing gate rolls the whole import back.
        await clearTable('chat_states');
        // The runtime plugin bindings (activeSessions, per-session config) were projected from the rows
        // about to be deleted. Remember which scopes they bound so the post-commit resync can retire
        // the ones the restore drops. Probed first: on PostgreSQL a failed SELECT would abort the
        // transaction, and a missing table is tolerated by clearTable below.
        const previousPluginBindings = (await queryRunner.hasTable('plugin_instances'))
          ? (
              (await queryRunner.query('SELECT "pluginId", "sessionScope", enabled FROM plugin_instances')) as Array<{
                pluginId: string;
                sessionScope: string | null;
                enabled: boolean | number;
              }>
            ).map(row => ({ ...row, enabled: Number(row.enabled) === 1 }))
          : [];
        // Integration Fabric + both DLQs: none carry an FK constraint to sessions (sessionId is provenance),
        // so clearing them here before the sessions DELETE keeps the replace-semantics complete.
        await clearTable('plugin_instances');
        await clearTable('conversation_mappings');
        await clearTable('ingress_events');
        await clearTable('webhook_delivery_failures');
        // Same rule, and it bites harder here: webhook_outbox_events carries UNIQUE(webhookId,
        // idempotencyKey), so without this clear a restore onto an instance that already holds the
        // archive's rows collides on every one of them, and the all-or-nothing gate below rolls the
        // whole import back. Restoring a backup onto the instance that produced it is exactly the
        // rollback flow, so leaving it out broke the recovery path rather than a corner of it.
        await clearTable('webhook_outbox_events');
        await clearTable('integration_delivery_failures');
        // status_updates has no FK to sessions; clear it explicitly so the replace is complete.
        await clearTable('status_updates');
        // Session ownership is CLUSTER RUNTIME STATE, not backup payload: which process currently holds
        // a session's engine, and until when. The replace below deletes it along with everything else,
        // and the sessions importer does not restore it (deliberately — see below), so without this the
        // committed rows come back unclaimed and the next lease renewal reads "claim lost" and tears
        // down engines that never stopped running.
        //
        // It must NOT be restored from the payload instead. export-data does `SELECT *`, so real backups
        // DO carry these columns even though SessionRow does not declare them — restoring them would
        // install the SOURCE host's nodeId with its still-future lease, and every start would then 409
        // "running on another node" until that lease lapsed. Strictly worse than the bug.
        //
        // Read through the SAME queryRunner (a repository would take a second connection and self-
        // deadlock on Postgres) and tolerate the columns being absent, so a database whose ownership
        // migration has been rolled back still imports.
        const preservedOwnership = await readSessionOwnership(queryRunner);
        // Stamped AFTER the read, so the remaining lease time carried forward later is measured from
        // the latest moment these values are known to have been true — never longer than they were.
        const ownershipReadAt = new Date();

        await queryRunner.query('DELETE FROM sessions');

        // Restore table by table in TABLE_IMPORTERS order (FK-safe: sessions first). The descriptors
        // carry each table's INSERT text, param mapping, and per-row skip guard; a missing or empty
        // table keeps its 0 count and contributes no warnings.
        const counts = Object.fromEntries(TABLE_IMPORTERS.map(importer => [importer.key, 0] as const)) as TableCounts;
        // SQLite only: archived datetime values are normalized to the form TypeORM writes there, so a
        // PostgreSQL-made backup compares and sorts like rows the app wrote itself.
        const datetimeColumns = isPostgres ? undefined : sqliteDatetimeColumns(this.dataDataSource);
        restore: for (const importer of TABLE_IMPORTERS) {
          const rows =
            importer.key === 'webhookDeliveryFailures'
              ? deduplicateArchivedWebhookFailures(data.tables.webhookDeliveryFailures ?? [])
              : data.tables[importer.key];
          if (!rows?.length) continue;
          const dateColumns = datetimeColumns?.get(importer.key) ?? [];
          for (const archivedRow of rows) {
            const source = archivedRow as unknown as Record<string, unknown>;
            const untypedRow = {
              ...source,
              ...Object.fromEntries(
                dateColumns
                  .filter(column => column in source)
                  .map(column => [column, toSqliteDatetime(source[column])]),
              ),
            };
            // `rows` was read from `data.tables[importer.key]`, so it holds exactly the row type this
            // descriptor's id/map/skip declare. That correlation is what the erased importer type
            // cannot carry, and this loop is the one place it is known — so the cast lives here rather
            // than at each of the three uses below.
            const row = untypedRow as never;
            const skipWarning = importer.skip?.(row, rows as never);
            if (skipWarning != null) {
              warnings.push(skipWarning);
              continue;
            }
            try {
              await insert(importer.sql, importer.map(row));
              counts[importer.key]++;
            } catch (err) {
              warnings.push(
                `Failed to import ${importer.label} ${importer.id(row)}: ${err instanceof Error ? err.message : String(err)}`,
              );
              // PostgreSQL aborts the transaction on a failed statement: every later one would fail with
              // "current transaction is aborted" and bury this row's real error. Stop at the first.
              if (isPostgres) break restore;
            }
          }
        }

        // Re-apply the claims read before the DELETE, for ids that exist in both. This runs BEFORE the
        // all-or-nothing gate below on purpose: a failure here must take the same rollback the gate
        // already implements. Degrading it to a notice and committing anyway would be worse than the
        // bug it fixes — on PostgreSQL a failed statement aborts the transaction, so the COMMIT would
        // execute as a ROLLBACK and the endpoint would report a fully discarded import as a success,
        // with per-table counts, to an operator restoring after data loss.
        // Skipped once a row has failed: the rollback below is already certain, and on PostgreSQL the
        // aborted transaction would only add a misleading warning.
        if (warnings.length === 0) {
          try {
            await restoreSessionOwnership(preservedOwnership, insert, ownershipReadAt);
          } catch (error) {
            warnings.push(
              `Failed to restore session ownership: ${error instanceof Error ? error.message : String(error)}`,
            );
          }
        }

        // An archive taken before 0.23.5 keys chat_states by session NAME. The migration that re-keys
        // them to the session id has already run on this database, so a restored name-keyed row would
        // never be read again and its mute, archive and pin state would be silently lost. Run the same
        // re-key here, inside the transaction. A failure takes the rollback below, like the ownership
        // restore, because on PostgreSQL it has already aborted the transaction.
        if (warnings.length === 0) {
          try {
            if (await queryRunner.hasTable('chat_states')) {
              await queryRunner.query(
                ReKeyChatStatesBySessionId1786500000000.rekey('name', 'id', { skipAlreadyKeyed: true }),
              );
            }
          } catch (error) {
            warnings.push(`Failed to re-key chat states: ${error instanceof Error ? error.message : String(error)}`);
          }
        }

        // The same holds for the 0.24.0 scrubs: an archive taken before them restores revoked messages
        // with their media, quote and reactions, and lid mappings with a broadcast id as the phone.
        if (warnings.length === 0) {
          try {
            await ScrubRevokedMessageContent1786900000000.scrub(queryRunner);
            await ScrubNonPhoneLidMappings1786950000000.scrub(queryRunner);
            // An archive taken before the neutral message vocabulary restores the raw wwebjs tokens, which
            // the boot-time backfill no longer converts on a migration-managed database.
            await BackfillLegacyMessageTypes1791300000000.backfill(queryRunner);
          } catch (error) {
            warnings.push(`Failed to clean restored rows: ${error instanceof Error ? error.message : String(error)}`);
          }
        }

        // send_idempotency_keys is not archived, so it is trimmed rather than cleared. A claim of a session
        // this restore dropped would outlive it by up to 24 h, and a later restore that brings the id back
        // would answer a retried send with the old stored response instead of sending it. The claims of a
        // session the restore keeps stay: a retry of a send made before the restore still replays.
        // Asked first rather than caught: on PostgreSQL a statement that fails, a missing table included,
        // aborts the whole import transaction, and every later statement then fails with it.
        if (warnings.length === 0 && (await queryRunner.hasTable('send_idempotency_keys'))) {
          try {
            // CAST: sessions.id is a uuid on PostgreSQL and the claim's sessionId a varchar, which `IN` does not
            // compare.
            await clearTable(
              'send_idempotency_keys',
              ' WHERE "sessionId" NOT IN (SELECT CAST("id" AS TEXT) FROM sessions)',
            );
          } catch (error) {
            warnings.push(
              `Failed to drop the send idempotency claims of removed sessions: ${error instanceof Error ? error.message : String(error)}`,
            );
          }
        }

        // "Replace all data" must be all-or-nothing: the import already DELETEd every row, so if any
        // INSERT failed we must roll back (restoring the pre-import data) rather than commit a
        // half-wiped DB and report success. A partial restore reported as imported:true was how
        // message history could silently vanish on a SQLite->Postgres migration. It must precede
        // every further statement: on PostgreSQL a failure has aborted the transaction, so the
        // normalization UPDATE below would throw and turn this answer into a 500.
        if (warnings.length > 0) {
          await queryRunner.rollbackTransaction();
          return {
            imported: false,
            counts,
            warnings,
            notices,
            ...engineStateAfterRollback,
          };
        }

        // Normalize imported statuses the same way boot does: an ACTIVE status (ready,
        // initializing, ...) in a backup describes the SOURCE host's engines, and restoring it
        // verbatim leaves rows reading ready with no engine anywhere - invisible to auto-start
        // (selects disconnected) and to the takeover sweep, until a process restart. Scoped to
        // CLAIMABLE rows: a PEER's preserved claim (a live engine backs the row elsewhere) keeps
        // the backup's status; this node's own claims normalize exactly like boot's reset does -
        // for a live self-engine the row understates reality until the next engine status event,
        // which is the same trade boot makes.
        const ACTIVE_STATUSES = [
          SessionStatus.READY,
          SessionStatus.INITIALIZING,
          SessionStatus.QR_READY,
          SessionStatus.AUTHENTICATING,
          SessionStatus.ACTION_REQUIRED,
        ];
        const claimable = this.ownership?.claimableWhere() ?? [{}];
        // An empty clause list means nothing is claimable (no rows to normalize). TypeORM also
        // rejects empty update criteria, so skip rather than build an empty OR.
        const normalized =
          claimable.length === 0
            ? { affected: 0 }
            : await queryRunner.manager.getRepository(SessionEntity).update(
                claimable.map(clause => ({ ...clause, status: In(ACTIVE_STATUSES) })),
                { status: SessionStatus.DISCONNECTED },
              );
        if (normalized.affected && normalized.affected > 0) {
          notices.push(
            `${normalized.affected} imported session(s) carried an active status (the source host's engines): ` +
              'restored as disconnected - start them via POST /api/sessions/:id/start or let auto-start adopt them.',
          );
        }

        // A wrong/empty/garbage backup file restores zero rows but the DELETE already ran — committing
        // would silently WIPE the database and report success. Refuse it and roll back instead. (#488)
        const totalRestored = Object.values(counts).reduce((sum, n) => sum + n, 0);
        if (totalRestored === 0) {
          await queryRunner.rollbackTransaction();
          return {
            imported: false,
            counts,
            warnings: [EMPTY_ARCHIVE_WARNING],
            notices,
            ...engineStateAfterRollback,
          };
        }

        await queryRunner.commitTransaction();
        committed = true;

        // Runtime reconciliation, part 2 (post-commit): the in-memory lid->phone mirror was warmed from
        // the OLD lid_mappings rows and is write-through only, so the just-restored table would never
        // reach it — resolution would keep serving stale entries (and miss restored ones) until the next
        // process start. Reload from the new DB contents. Best-effort: a miss falls back to engine
        // re-resolution, so a reload failure degrades instead of failing the (already committed) import.
        // The chat-state mirror has the same shape: left stale, GET /chats would serve the old
        // archived/pinned/muted flags and the next live update would write them back over the restore.
        await this.lidMappingStore?.reload();
        await this.chatStateStore?.reload();

        // Plugin runtime bindings are projected from plugin_instances rows and saved to the plugin
        // registry, and the boot pass only ever adds to them. Without this resync, an instance the
        // restore dropped keeps receiving its session's hooks with its old config, even after a
        // restart. Best-effort: the import is already committed.
        if (this.moduleRef) {
          try {
            await this.moduleRef.get(ScopeBindingService, { strict: false }).resyncAfterImport(previousPluginBindings);
          } catch (error) {
            restartRequired = true;
            notices.push(
              `Plugin instance bindings could not be re-applied after the restore ` +
                `(${error instanceof Error ? error.message : String(error)}): check each plugin's active sessions ` +
                `and per-session config (GET /api/plugins/:id, PUT /api/plugins/:id/sessions) against its restored instances.`,
            );
          }
        }

        // Audit the destructive replace-all restore, only on the committed-success path (the rollback /
        // refused-empty branches above return without emitting, since no data actually changed). Any
        // warnings would have taken the rollback branch, so warnings.length is always 0 here — record
        // only the per-table counts.
        await this.auditService?.logInfo(AuditAction.INFRA_DATA_IMPORTED, { metadata: { counts } });

        // restartRequired was computed in the pre-flight, from three independent causes: orphans left
        // running (force=true legacy path), a stopOrphans teardown that failed for at least one
        // engine, and sessions held by another node, which this request cannot reach to stop. It is
        // also set above when the post-commit plugin binding re-sync fails; a restart does not repair
        // that one, so its notice names the manual check instead.
        return {
          imported: true,
          counts,
          warnings,
          notices,
          restartRequired,
          orphanedEngines,
          stoppedOrphanEngines,
          failedOrphanEngines,
        };
      } catch (error) {
        await queryRunner.rollbackTransaction();
        throw error;
      } finally {
        await queryRunner.release();
      }
    } finally {
      // A restore that did not commit keeps those sessions, but a batch run that captured their writes before
      // the close stays stopped, so its row is failed before the release, as a failed delete does. Their
      // engines are gone, so the batch could not have sent anyway. Not inside a transaction another caller
      // opened on the shared connection while the writes drained: the fail would roll back with it.
      if (foreignTransaction && retired.length > 0 && !(await awaitNoOpenTransaction(this.dataDataSource))) {
        this.logger.warn('Failing the unfinished batches of a refused import inside another open transaction', {
          action: 'infra_import_foreign_transaction_open',
          sessionIds: retired.map(({ id }) => id),
        });
      }
      for (const { id } of committed ? [] : retired) {
        await failUnfinishedSessionBatches(this.dataDataSource, id).catch((error: unknown) =>
          this.logger.warn(
            `Could not fail the unfinished batches of session ${id} after an import that did not commit`,
            {
              sessionId: id,
              action: 'infra_import_batch_fail_failed',
              error: error instanceof Error ? error.message : String(error),
            },
          ),
        );
      }
      for (const { writes } of retired) writes.release();
      // Its own finally, so a throwing release() cannot strand the token either.
      resumeLossDetection?.();
    }
  }
}