Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

32.6 KB
Raw Blame
import { Injectable, OnModuleInit } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { In, IsNull, Not, Raw, Repository } from 'typeorm';
import { LidMapping } from './lid-mapping.entity';
import { userPart } from './wa-id';
import { createLogger } from '../../common/services/logger.service';
import { resolveNonNegativeIntEnv } from '../../config/configuration';

// Default cap on the in-memory lid->phone mirror. Every other long-lived map in the engine surface is
// bounded (the per-session lidPhoneCache is 5000); the LID mirror was the lone exception. A miss falls
// back to engine re-resolution (a reverse lookup reads the table), so the cap trades a re-resolution for
// bounded memory, never data loss.
export const LID_MAPPING_CACHE_DEFAULT = 5000;

/**
 * SQLite binds at most 32766 variables in one statement (Postgres 65535), so an `IN (...)` over a
 * large allowlist is chunked. Small enough to stay well inside both, large enough that a realistic
 * allowlist is one round trip.
 */
const LID_QUERY_CHUNK = 500;

/**
 * How often a failed write is logged. A database that is down or full takes one failed statement per report
 * that has something to write (each inbound message that carries the lid, while its write keeps failing),
 * since a report held back would leave the table naming a number the contact no longer has; the warning is
 * what is bounded, to one in this interval for the whole store, with a count of the failures in between.
 */
const LID_WRITE_WARN_MS = 60_000;

function chunk<T>(items: T[], size = LID_QUERY_CHUNK): T[][] {
  const out: T[][] = [];
  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
  return out;
}

/**
 * Narrow read/write port over the `lid -> phone` table. The Baileys session store depends on this (sync
 * reads on the resolution hot path + write-through) and the message from-filter depends on the reverse
 * lookup - both on the interface, not the concrete service, so each stays unit-testable with a fake
 * (mirrors {@link BaileysMessageStore}).
 */
export interface LidMappingStore {
  /**
   * Sync read from the in-memory cache: phone digits, `null` = known-unresolved, `undefined` = never
   * seen. A miss is warmed from the persisted table in the background, so a later read can hit.
   */
  getCached(lid: string): string | null | undefined;
  /**
   * Resolve any WA JID through the mirror: the phone digits for its user part, `null` when the lid
   * is known-unresolved, unreported or never seen. This hot-cache view may lag another process;
   * alias authorization and rule matching await the persisted reads below.
   */
  resolveLid(jid: string): string | null;
  /** Sync reverse lookup: the lids currently mapped to this phone (used by the message from-filter). */
  lidsForPhone(phone: string): string[];
  /** The phone the table holds for a lid JID, read from the database; null when none is stored. */
  findPhoneForLid?(jid: string): Promise<string | null>;
  /** The lids the table maps to these phone digits, read from the database. */
  findLidsForPhone?(phone: string): Promise<string[]>;
  /**
   * Write-through: update the cache + persist. A phone is last-write-wins. A session reporting the phone
   * this node already holds takes the row, unless this node already counted a report of it from that
   * session: after s1, s2, s1 report one phone the owner is s2. A `null` phone records a negative result,
   * and replaces a stored phone only when its owner (or none, or one since deleted or logged out) gives it.
   * Never rejects; resolves false when its write failed.
   */
  remember(lid: string, phone: string | null, sessionId?: string): Promise<boolean>;
  /** Keep a cached lookup for display without authorizing it or replacing a stored phone or negative. */
  rememberIfUnknown?(lid: string, phone: string, sessionId?: string): Promise<boolean>;
}

/**
 * Backs lid resolution with the persisted {@link LidMapping} table. A bounded synchronous mirror
 * serves display and hot-cache reads, while authorization and rule matching await the table's current
 * reported pairings. Write-through keeps the local forward and reverse maps warm.
 *
 * The forward map is bounded by an LRU cap (`LID_MAPPING_CACHE_MAX`, default 5000) so a long-running,
 * contact-heavy account does not accumulate one entry per distinct LID ever seen into a slow memory leak.
 * A cache miss is warmed from the table in the background (rows past the preload cap stay resolvable)
 * and otherwise falls back to engine re-resolution (the table remains the source of truth), so eviction
 * only costs a re-resolution, never data loss. The reverse map has no such warm path (nothing looks a
 * lid up by phone), so a phone-keyed filter uses {@link findLidsForPhone}, which reads the table. The
 * reverse map is reconciled on each eviction so it does not retain entries for LIDs no longer in the
 * forward cache.
 */
@Injectable()
export class LidMappingStoreService implements LidMappingStore, OnModuleInit {
  private readonly logger = createLogger('LidMappingStore');
  private readonly lidToPhone = new Map<string, string | null>();
  /** Origin of resident display-only mappings, bounded and evicted with the forward mirror. */
  private readonly unreported = new Set<string>();
  private readonly phoneToLids = new Map<string, Set<string>>();
  /** Repository fallbacks in flight, one per lid, so a hot miss path can't stack duplicate queries. */
  private readonly pendingLookups = new Set<string>();
  /**
   * Lids the table answered for and had no row for. {@link pendingLookups} collapses only the lookups
   * that overlap a query already in flight, so without this every DISPATCH that names an unmapped lid
   * issued a fresh query for it, and the callers are on hot paths: a webhook filter resolves both the
   * event's actor and each of its own rule values, on every dispatch.
   *
   * Cleared for a lid the moment this process learns a mapping for it ({@link index}), and wholesale
   * when the table is reloaded. An absence is never RECORDED for a lid this process already holds or
   * is still writing ({@link unsettledWrites}), which is what keeps a query that raced a write from
   * shadowing the row it could not see yet.
   *
   * What it does NOT notice is a row ANOTHER process writes: that mapping stays unseen here until
   * this process learns it or reloads, exactly as a phone already cached in {@link lidToPhone} does.
   * Bounded by the same cap as the forward map, oldest-recorded first (the forward map is ordered by
   * recency of USE, this one by when the absence was recorded).
   */
  private readonly absentFromTable = new Set<string>();
  /**
   * Lids whose row this process has indexed but not yet committed. `remember()` updates the in-memory
   * maps synchronously and writes the table afterwards, so between the two a table read answers "no
   * row" about a mapping that is about to exist. The forward map cannot stand in for this: the LRU
   * can evict the entry inside that same window, leaving it indistinguishable from never-learned.
   * Counted per lid, so the first of two overlapping writes settling does not clear the second. The
   * latest actual report's token remains until all older writes settle, isolating their late results.
   */
  private readonly unsettledWrites = new Map<
    string,
    { count: number; latestReport?: object; latestOperation?: { phone: string | null } }
  >();
  /**
   * Lids a write started for while their table read was in flight. That read may have run before the
   * write committed, so whatever it answers predates the mapping this process now holds.
   */
  private readonly racedLookups = new Set<string>();
  /**
   * Sessions counted as having written or reported the phone a lid holds in {@link lidToPhone} (a loaded
   * row counts its owner). An uncounted session reporting the same phone takes the row and is counted
   * after its write succeeds; one already counted preserves the owner while checking for a changed row
   * on another node. So the row names the latest uncounted session to report
   * the phone, not the latest to report it: after s1, s2, s1 report one phone it names s2, and s2's
   * negative clears a phone s1 still sees. Started anew when the phone changes, dropped with the cached
   * entry, on an applied negative and on any release. A failed write does not forget an earlier success.
   */
  private readonly seenBy = new Map<string, Set<string>>();
  /**
   * Cached phones whose report is pending or failed, or whose cached contradiction failed to persist.
   * Kept only while the cache holds that phone, until a current write lands or a negative clears it.
   */
  private readonly failedWrites = new Set<string>();
  /** When a failed write was last logged, on {@link now}, and how many have failed since without a line. */
  private writeWarnedAt = -Infinity;
  private unloggedWriteFailures = 0;
  /** Monotonic clock in ms (a seam for tests). */
  private readonly now = (): number => performance.now();
  // 0 = unbounded (legacy behaviour). Every other long-lived map in the engine surface is bounded, so
  // the default is finite; the env override exists for operators who explicitly want the old behaviour.
  private readonly maxCachedLids: number;

  constructor(
    @InjectRepository(LidMapping, 'data')
    private readonly repo: Repository<LidMapping>,
  ) {
    this.maxCachedLids = resolveNonNegativeIntEnv(process.env.LID_MAPPING_CACHE_MAX, LID_MAPPING_CACHE_DEFAULT);
  }

  async onModuleInit(): Promise<void> {
    await this.reload();
  }

  /**
   * (Re)load the in-memory mirror from the table. Called on boot, and by the infra data import after
   * a committed full-replace restore — the mirror is otherwise write-through only, so restored rows
   * would never reach it and entries the restore removed would stay resolvable until the next start.
   * Never throws: a missing table (migration not yet applied) or a read error must not block boot or
   * fail the import — resolution falls back to engine re-resolution until the table is readable.
   */
  async reload(): Promise<void> {
    // Dropped before the read too: a restore may have replaced the table, so if the read fails, a lid
    // not cached must read through rather than trust a stale absence.
    this.absentFromTable.clear();
    try {
      // Deterministic preload: an unordered find() followed by LRU eviction keeps an ARBITRARY
      // subset once the table exceeds the cap. Order by last-write and take at most the cap, so
      // the resident subset is the most-recently-written mappings; older rows stay persisted and
      // are warmed back on the first cache miss (see getCached).
      const rows = await this.repo.find({
        order: { updatedAt: 'DESC' },
        take: this.maxCachedLids > 0 ? this.maxCachedLids : undefined,
      });
      this.lidToPhone.clear();
      this.unreported.clear();
      this.phoneToLids.clear();
      this.seenBy.clear();
      this.failedWrites.clear();
      for (const writing of this.unsettledWrites.values()) {
        delete writing.latestReport;
        delete writing.latestOperation;
      }
      // A reload re-reads the table, so every recorded absence is a fresh question again.
      this.absentFromTable.clear();
      // Oldest first, so the newest row ends at the most-recent end of the LRU rather than the first
      // one evicted.
      for (const row of rows.reverse()) {
        this.index(row.lid, row.phone, row.sessionId, row.isReported);
      }
      this.logger.log(
        `Loaded ${rows.length} lid->phone mappings into cache${this.maxCachedLids ? ` (cap ${this.maxCachedLids})` : ''}`,
      );
    } catch (err) {
      this.logger.warn(`Could not preload lid->phone mappings: ${err instanceof Error ? err.message : String(err)}`);
    }
  }

  getCached(lid: string): string | null | undefined {
    // LRU touch: re-insert the entry so iteration order (insertion order for Map) tracks recency.
    // A missed lookup returns undefined without disturbing the order.
    if (this.lidToPhone.has(lid)) {
      const phone = this.lidToPhone.get(lid);
      this.lidToPhone.delete(lid);
      this.lidToPhone.set(lid, phone as string | null);
      return phone;
    }
    this.warmFromTable(lid);
    return undefined;
  }

  resolveLid(jid: string): string | null {
    const lid = userPart(jid);
    return this.unreported.has(lid) ? null : (this.getCached(lid) ?? null);
  }

  lidsForPhone(phone: string): string[] {
    const set = this.phoneToLids.get(phone);
    return set ? [...set].filter(lid => !this.unreported.has(lid)) : [];
  }

  /**
   * Reverse lookup that also reads the table. {@link lidsForPhone} only sees lids resident in the
   * forward cache, and nothing phone-keyed ever warms it, so a mapping past the preload cap or
   * evicted by the LRU would stay invisible to a phone filter for good. For callers that can await
   * (the message and status filters, the handover gate, the API-key chat fence). Same rule as
   * {@link lidsForPhonesPersisted}; a read error falls back to the cache alone.
   */
  async findLidsForPhone(phone: string): Promise<string[]> {
    try {
      return (await this.readLidsForPhones([phone]))[phone];
    } catch (err) {
      this.logger.warn(`Could not read lids for a phone: ${err instanceof Error ? err.message : String(err)}`);
      return this.lidsForPhone(phone).filter(lid => !this.unreported.has(lid));
    }
  }

  /**
   * Batched forward lookup for a list filter: lid user-part -> phone digits. Chunked queries for the
   * whole allowlist instead of one per entry, and the TABLE wins over the mirror so a stale cached
   * negative cannot shadow a mapping another node persisted.
   */
  async phonesForLidsPersisted(lids: string[]): Promise<Record<string, string | null>> {
    const out: Record<string, string | null> = {};
    if (lids.length === 0) return out;
    // The mirror is only the fallback for a failed table read, so it is read without getCached:
    // that warms every miss with a findOne of its own, one per lid ahead of the batched query below.
    for (const lid of lids) out[lid] = this.unreported.has(lid) ? null : (this.lidToPhone.get(lid) ?? null);
    try {
      for (const batch of chunk(lids)) {
        const rows = await this.repo.find({ where: { lid: In(batch) } });
        for (const lid of batch) out[lid] = null;
        // The table WINS: a stale cached negative must not shadow a mapping another node persisted.
        for (const row of rows) out[row.lid] = this.rowPhone(row.lid, row.phone, row.isReported);
      }
    } catch {
      // The table may not exist yet (migration pending); the mirror is the best available answer.
    }
    return out;
  }

  /** Batched reverse lookup, companion to {@link phonesForLidsPersisted}: phone digits -> lids. */
  async lidsForPhonesPersisted(phones: string[]): Promise<Record<string, string[]>> {
    try {
      return await this.readLidsForPhones(phones);
    } catch {
      // The table may not exist yet (migration pending); the cache is the best available answer.
      return Object.fromEntries(
        phones.map(phone => [phone, this.lidsForPhone(phone).filter(lid => !this.unreported.has(lid))]),
      );
    }
  }

  /** Read only current table rows on success; a resident mapping cannot restore a deleted row. */
  private async readLidsForPhones(phones: string[]): Promise<Record<string, string[]>> {
    const out: Record<string, Set<string>> = Object.fromEntries(phones.map(phone => [phone, new Set<string>()]));
    for (const batch of chunk(phones)) {
      for (const { lid, phone, isReported } of await this.repo.find({ where: { phone: In(batch) } })) {
        if (!phone || !out[phone]) continue;
        if (this.rowPhone(lid, phone, isReported) === phone) out[phone].add(lid);
      }
    }
    return Object.fromEntries(phones.map(phone => [phone, [...out[phone]]]));
  }

  /** This process has a phone write for the lid that the table does not have: in flight, or failed. */
  private unstored(lid: string): boolean {
    return this.unsettledWrites.has(lid) || this.failedWrites.has(lid);
  }

  /**
   * The phone a lid's row answers. The table is the truth across nodes, but while a phone this process holds
   * for the lid is not stored yet, a row that differs may be the number it replaces: the lid then answers
   * none, so no fence lookup admits either one until the write lands.
   */
  private rowPhone(lid: string, phone: string | null, isReported = false): string | null {
    if (!isReported || (this.unreported.has(lid) && this.unstored(lid))) return null;
    const cached = this.lidToPhone.get(lid);
    return this.unstored(lid) && cached !== undefined && cached !== phone ? null : phone;
  }

  /**
   * Forward lookup for callers that can await: the API-key chat fence and every chat-bound read
   * behind it (message history and media, the quoted body, status and handover filters). The table
   * answers first, the in-memory mirror only when the read fails. The mirror alone is
   * not enough: it is LRU-evicted at `LID_MAPPING_CACHE_MAX`, and nothing refreshes it when another
   * node re-maps a lid in the shared table, so a cache-first answer could resolve the same lid to
   * a phone the fence no longer sees, and a read behind the fence would serve that other chat. The
   * row is not indexed into the cache, so a lookup cannot evict hot entries. A row is vetoed while this
   * process has a different phone for the lid in flight or failed ({@link rowPhone}); with no row, no
   * alias is authorized until a report commits.
   */
  async findPhoneForLid(jid: string): Promise<string | null> {
    const lid = userPart(jid);
    try {
      const row = await this.repo.findOne({ where: { lid } });
      return row ? this.rowPhone(lid, row.phone, row.isReported) : null;
    } catch (err) {
      this.logger.warn(`Could not read the phone for a lid: ${err instanceof Error ? err.message : String(err)}`);
    }
    return this.unreported.has(lid) ? null : (this.getCached(lid) ?? null);
  }

  /**
   * A cached lookup can introduce display data, but cannot replace a stored phone or negative or grant
   * alias access. A conflicting positive revokes alias trust until an engine reports the mapping again.
   */
  async rememberIfUnknown(lid: string, phone: string, sessionId?: string): Promise<boolean> {
    if (!lid) return true;
    const cached = this.lidToPhone.get(lid);
    const lookup = { phone };
    if (cached && cached !== phone) {
      this.unreported.add(lid);
      this.seenBy.set(lid, new Set());
    }
    const reporters = this.seenBy.get(lid);
    const writing = this.beginWrite(lid, lookup);
    try {
      await this.repo
        .createQueryBuilder()
        .insert()
        .values({ lid, phone, sessionId: sessionId ?? null, updatedAt: new Date() })
        .orIgnore()
        .execute();
      const { affected } = await this.repo.update(
        { lid, phone: Raw(column => `${column} <> :lookupPhone`, { lookupPhone: phone }), isReported: true },
        { isReported: false, updatedAt: () => '"updatedAt"' },
      );
      if (
        affected &&
        writing.latestOperation === lookup &&
        this.seenBy.get(lid) === reporters &&
        this.lidToPhone.has(lid)
      )
        this.unreported.add(lid);
      // No optimistic mirror write: another node may already hold a newer phone or negative.
      this.absentFromTable.delete(lid);
      return true;
    } catch (err) {
      if (writing.latestOperation === lookup && this.seenBy.get(lid) === reporters && this.unreported.has(lid))
        this.failedWrites.add(lid);
      this.warnWriteFailed(`Could not store lid mapping: ${err instanceof Error ? err.message : String(err)}`);
      return false;
    } finally {
      this.endWrite(lid, writing);
    }
  }

  async remember(lid: string, phone: string | null, sessionId?: string): Promise<boolean> {
    if (!lid) return true;
    const cached = this.lidToPhone.get(lid);
    // Unseen-or-changed only, or a phone a session reports here for the first time: a no-op write would
    // just churn updatedAt.
    const seen =
      !this.unreported.has(lid) &&
      cached === phone &&
      (phone === null || !sessionId || this.seenBy.get(lid)?.has(sessionId));
    // A negative is not cached until the table has taken it: see clear().
    if (!seen && phone !== null) this.index(lid, phone, null);
    if (phone !== null) this.failedWrites.add(lid);
    const reporters = this.seenBy.get(lid);
    const report = { phone };
    const writing = this.beginWrite(lid, report, true);
    try {
      if (seen && phone !== null) {
        // A peer may have changed or revoked this row since this node counted the report. Keep the
        // owner and timestamp for the same phone, but let the latest actual report replace another one.
        const changed = '"lid_mappings"."phone" IS NULL OR "lid_mappings"."phone" <> EXCLUDED."phone"';
        const [insert, parameters] = this.repo
          .createQueryBuilder('lid_mappings')
          .insert()
          .values({ lid, phone, sessionId: sessionId ?? null, isReported: true, updatedAt: new Date() })
          .getQueryAndParameters();
        await this.repo.query(
          insert +
            ` ON CONFLICT ("lid") DO UPDATE SET "phone" = EXCLUDED."phone", "isReported" = true, ` +
            `"sessionId" = CASE WHEN ${changed} THEN EXCLUDED."sessionId" ELSE "lid_mappings"."sessionId" END, ` +
            `"updatedAt" = CASE WHEN ${changed} THEN EXCLUDED."updatedAt" ELSE "lid_mappings"."updatedAt" END ` +
            `WHERE ${changed} OR "lid_mappings"."isReported" = false`,
          parameters,
        );
      } else if (phone === null) await this.clear(lid, sessionId ?? null, seen, report);
      else {
        await this.repo.upsert({ lid, phone, sessionId: sessionId ?? null, isReported: true, updatedAt: new Date() }, [
          'lid',
        ]);
      }
      // Count only a stored report in this phone's current cache epoch. A late completion after
      // P -> Q -> P must not count the first P as a report of the replacement P.
      if (phone !== null && reporters && this.seenBy.get(lid) === reporters) {
        const operation = writing.latestOperation;
        let reported = !this.unreported.has(lid);
        // A consistent lookup may have revoked the old stored phone while this actual write was
        // in flight. Only the current reported row can establish which SQL statement landed last.
        if (!reported && writing.latestReport === report && operation?.phone === phone) {
          const row = await this.repo.findOne({ where: { lid } }).catch(() => null);
          reported = row?.isReported === true && row.phone === phone;
        }
        if (
          reported &&
          this.seenBy.get(lid) === reporters &&
          writing.latestReport === report &&
          writing.latestOperation === operation &&
          operation?.phone === phone
        ) {
          this.failedWrites.delete(lid);
          this.unreported.delete(lid);
        }
        if (sessionId && this.seenBy.get(lid) === reporters) reporters.add(sessionId);
      }
      return true;
    } catch (err) {
      this.warnWriteFailed(
        `Failed to persist lid->phone mapping for ${lid}: ${err instanceof Error ? err.message : String(err)}`,
      );
      return false;
    } finally {
      this.endWrite(lid, writing);
    }
  }

  /** Keep report and lookup ordering until all older writes settle, without counting a lookup as a report. */
  private beginWrite(lid: string, operation: { phone: string | null }, actual = false) {
    const writing = this.unsettledWrites.get(lid) ?? { count: 0 };
    writing.count++;
    writing.latestOperation = operation;
    if (actual) writing.latestReport = operation;
    this.unsettledWrites.set(lid, writing);
    if (this.pendingLookups.has(lid)) this.racedLookups.add(lid);
    return writing;
  }

  private endWrite(lid: string, writing: { count: number }): void {
    if (this.unsettledWrites.get(lid) === writing && --writing.count === 0) this.unsettledWrites.delete(lid);
  }

  /**
   * Record that a session found no phone for a lid. The row is shared by every session, and one account
   * can see a contact's number while another cannot, so a negative replaces the row only when it holds
   * no phone or the phone was written by this session (or by none, or by one no longer linked: gone from
   * `sessions`, or logged out, which clears its `phone`); another linked session's mapping stays. The check
   * is part of the update, not a read before it, so a phone stored meanwhile is never overwritten. When the
   * row is cleared the cached entry is dropped rather than set: a phone written while the statements ran may
   * be the newer value, and the next read takes whichever the table holds.
   */
  private async clear(
    lid: string,
    sessionId: string | null,
    preserveEmpty: boolean | undefined,
    report: object,
  ): Promise<void> {
    const updatedAt = new Date();
    // Creates the row when there is none; an existing one is left to the conditional update.
    await this.repo
      .createQueryBuilder()
      .insert()
      .values({ lid, phone: null, sessionId, isReported: true, updatedAt })
      .orIgnore()
      .execute();
    const replaceable = [
      { lid, phone: IsNull() },
      { lid, sessionId: IsNull() },
      // A session deleted without its rows being released (an older release, a crash, a restored backup)
      // owns them no more than a released one does, and neither does one logged out: it reports nothing
      // until it is linked again. CAST: sessions.id is a uuid on PostgreSQL.
      {
        lid,
        sessionId: Raw(
          owner => `${owner} NOT IN (SELECT CAST(s."id" AS TEXT) FROM sessions s WHERE s."phone" IS NOT NULL)`,
        ),
      },
      ...(sessionId ? [{ lid, sessionId }] : []),
    ];
    // A loaded negative may be stale after a peer's positive report. Recheck ownership atomically,
    // preserving an unchanged empty row's owner and timestamp rather than trusting this mirror.
    const eligible = preserveEmpty
      ? replaceable.slice(1).map(where => ({ ...where, phone: Not(IsNull()) }))
      : replaceable;
    const { affected } = await this.repo.update(eligible, { phone: null, sessionId, isReported: true, updatedAt });
    if (!affected || this.unsettledWrites.get(lid)?.latestReport !== report) return;
    const cached = this.lidToPhone.get(lid);
    this.lidToPhone.delete(lid);
    this.unreported.delete(lid);
    this.seenBy.delete(lid);
    this.failedWrites.delete(lid);
    if (cached) this.unindex(lid, cached);
    this.absentFromTable.delete(lid);
  }

  /** Log a failed write at most once per {@link LID_WRITE_WARN_MS}, counting the ones in between. */
  private warnWriteFailed(message: string): void {
    const now = this.now();
    if (now - this.writeWarnedAt < LID_WRITE_WARN_MS) {
      this.unloggedWriteFailures++;
      return;
    }
    const unlogged = this.unloggedWriteFailures;
    this.logger.warn(unlogged ? `${message} (${unlogged} more failed since the last warning)` : message);
    this.writeWarnedAt = now;
    this.unloggedWriteFailures = 0;
  }

  /**
   * Hand a deleted session's rows to no session. Its id never comes back (a re-created session gets a
   * new one); {@link clear} also treats an owner missing from `sessions` as none, which covers a delete
   * that never got here. The rows stay: the table is shared. Never throws: the session is already gone.
   */
  async releaseSession(sessionId: string): Promise<void> {
    // A counted reporter preserves the current owner on a repeated phone report, so a released row
    // would stay ownerless. Drop every set even if the update fails, so the next report takes ownership.
    this.seenBy.clear();
    try {
      // updatedAt is kept: no mapping changed, and the preload ranks rows by it.
      await this.repo.update({ sessionId }, { sessionId: null, updatedAt: () => '"updatedAt"' });
    } catch (err) {
      this.logger.warn(`Could not release lid mappings: ${err instanceof Error ? err.message : String(err)}`);
    }
  }

  /**
   * Repository fallback for a cache miss. Rows past the preload cap (or evicted by the LRU) are
   * still persisted, so a miss is warmed from the table: THIS lookup still returns undefined —
   * the sync read contract can't await, and callers fall back to engine re-resolution, but the
   * next one hits. A table miss IS remembered, so an unmapped lid stops re-querying on every
   * lookup ({@link absentFromTable}), but only when nothing learned that lid in the meantime;
   * a read error is swallowed (the table may not exist yet), the same posture as reload().
   */
  private warmFromTable(lid: string): void {
    if (!lid || this.pendingLookups.has(lid) || this.absentFromTable.has(lid)) return;
    this.pendingLookups.add(lid);
    // Captured BEFORE the query: a write for this lid that has not reached the table yet means the
    // answer is already stale, whatever it says. The forward-map check below cannot see that case,
    // because `remember()` indexes synchronously and the LRU can evict the entry again before the
    // query answers, at which point the map looks exactly like "never learned".
    const writeInFlight = this.unsettledWrites.has(lid);
    void this.repo
      .findOne({ where: { lid } })
      .then(row => {
        // A write that was unsettled when the query ran, or started while it was in flight, is newer
        // than either answer: a row would be the phone it replaces, served as a hit after the write
        // commits, and an absence would block the warm-back once the LRU evicts the forward entry.
        // Neither is recorded, so the next miss reads the table again.
        if (writeInFlight || this.racedLookups.has(lid)) return;
        // Last-write-wins: a mapping indexed while the lookup was in flight is newer.
        if (row && !this.lidToPhone.has(row.lid)) {
          this.index(row.lid, row.phone, row.sessionId, row.isReported);
          return;
        }
        if (!row && !this.lidToPhone.has(lid)) this.noteAbsent(lid);
      })
      .catch(() => undefined)
      .finally(() => {
        this.pendingLookups.delete(lid);
        this.racedLookups.delete(lid);
      });
  }

  /** Update both in-memory indexes, dropping any stale reverse entry from a previous phone. */
  private index(lid: string, phone: string | null, sessionId: string | null, isReported = true): void {
    const previouslyReported = !this.unreported.has(lid);
    if (isReported) this.unreported.delete(lid);
    else this.unreported.add(lid);
    const prev = this.lidToPhone.get(lid);
    if (prev && prev !== phone) {
      this.unindex(lid, prev);
    }
    const seen = (isReported && previouslyReported && prev === phone && this.seenBy.get(lid)) || new Set<string>();
    if (isReported && sessionId) seen.add(sessionId);
    if (phone) this.seenBy.set(lid, seen);
    else this.seenBy.delete(lid);
    // Re-insert (delete + set) so the entry moves to the most-recent end of the LRU order even on update.
    this.lidToPhone.delete(lid);
    this.lidToPhone.set(lid, phone);
    if (phone) {
      const set = this.phoneToLids.get(phone) ?? new Set<string>();
      set.add(lid);
      this.phoneToLids.set(phone, set);
    }
    this.absentFromTable.delete(lid);
    this.evictIfOverCap();
  }

  /**
   * Record that the table holds no row for this lid, bounded oldest-recorded first.
   *
   * Skipped entirely when the cap is disabled: that mode is the legacy unbounded cache, and an
   * absence set is the one map here that grows on ids a caller supplies rather than on mappings the
   * account really has, so leaving it unbounded would be a leak an operator never opted into.
   */
  private noteAbsent(lid: string): void {
    if (!this.maxCachedLids) return;
    this.absentFromTable.add(lid);
    while (this.absentFromTable.size > this.maxCachedLids) {
      const oldest = this.absentFromTable.values().next().value;
      if (oldest === undefined) break;
      this.absentFromTable.delete(oldest);
    }
  }

  /** Evict the least-recently-used forward entry (and its reverse index) while over the cap. */
  private evictIfOverCap(): void {
    if (!this.maxCachedLids) return; // unbounded
    while (this.lidToPhone.size > this.maxCachedLids) {
      const oldest = this.lidToPhone.keys().next().value;
      if (oldest === undefined) break;
      const phone = this.lidToPhone.get(oldest);
      this.lidToPhone.delete(oldest);
      this.unreported.delete(oldest);
      this.seenBy.delete(oldest);
      this.failedWrites.delete(oldest);
      const writing = this.unsettledWrites.get(oldest);
      if (writing) {
        delete writing.latestReport;
        delete writing.latestOperation;
      }
      if (phone) this.unindex(oldest, phone);
    }
  }

  /** Drop a lid from its phone's reverse entry, and the entry itself once no lid is left under it. */
  private unindex(lid: string, phone: string): void {
    const set = this.phoneToLids.get(phone);
    if (set?.delete(lid) && set.size === 0) this.phoneToLids.delete(phone);
  }
}