mercury-agent 0.7.0 → 0.8.1

package/docs/setup-whatsapp.md

@@ -86,6 +86,38 @@ mercury service install
 | Messages not arriving | Check `MERCURY_ENABLE_WHATSAPP=true` and re-auth |
 | Old messages appear on startup | Normal — Mercury ignores pre-connection messages |
 
+## Identity: LID vs Phone Number
+
+WhatsApp non-deterministically identifies the same person by either their
+phone-number JID (`972501234567@s.whatsapp.net`) or an anonymized LID
+(`24417056866472@lid`). Mercury canonicalizes every inbound identity to the
+phone form whenever the mapping is known, so a person always resolves to one
+caller id, one conversation, and one DM auto-space.
+
+How it works:
+
+1. Baileys attaches the alternate form on many message keys; when it does,
+   Mercury uses the phone form and records the LID↔phone pair in the
+   `wa_identity_aliases` table (log line: `WhatsApp identity alias learned`).
+2. When a message arrives LID-tagged without the alternate field, Mercury
+   consults Baileys' internal mapping store, then its own alias table.
+3. If no mapping is known anywhere, the LID is kept as-is. This self-heals:
+   the moment a later message reveals the pair, the person's phone-keyed
+   conversation **adopts** the space that was created under the LID — history,
+   config, and settings are preserved, and per-user roles/mutes are rewritten
+   to the canonical caller id (log line: `dm-auto-space: adopted existing
+   space for canonical identity`). Existing `dm-<lid-digits>` space ids keep
+   their name; only the identity resolution changes.
+
+If a person somehow ended up with **two** spaces (one LID-keyed, one
+phone-keyed) before canonicalization existed, the phone-keyed space wins and
+a warning names both spaces (`same person has two spaces`) so you can merge
+or delete the stale one manually.
+
+A LID's digits are unrelated to the phone number — Mercury never guesses a
+mapping; pairs only come from WhatsApp itself. For support cases you can
+insert a pair manually into `wa_identity_aliases` with `source = 'manual'`.
+
 ## Security
 
 - Credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/src/adapters/whatsapp-identity.ts

@@ -0,0 +1,183 @@
+import { jidNormalizedUser } from "@whiskeysockets/baileys";
+
+/**
+ * WhatsApp canonical caller identity.
+ *
+ * WhatsApp non-deterministically identifies the same person by either their
+ * phone-number JID (`<digits>@s.whatsapp.net`) or an anonymized LID
+ * (`<digits>@lid`). Everything here resolves an inbound identity to its
+ * phone form whenever a mapping is known, so downstream consumers
+ * (callerId, thread ids, spaces, roles, extensions) see one stable identity.
+ *
+ * Resolution priority:
+ *   1. Message-key alt field (`remoteJidAlt` / `participantAlt`)
+ *   2. Baileys' internal LID store (`signalRepository.lidMapping`) — async only
+ *   3. Mercury's persisted alias table (via WaAliasStore)
+ *   4. No mapping → keep the LID (consistent, self-heals once a pair is learned)
+ *
+ * A LID's digits are NOT a phone number — a pair may only come from Baileys.
+ */
+
+/** Narrow persistence interface so the adapter never imports Db directly. */
+export interface WaAliasStore {
+  getPnForLid(lid: string): string | null;
+  learn(lid: string, pn: string, source: string): void;
+}
+
+export function isLidJid(jid: string): boolean {
+  return jid.endsWith("@lid");
+}
+
+export function isPnJid(jid: string): boolean {
+  return jid.endsWith("@s.whatsapp.net");
+}
+
+/** Strip device suffixes (`123:45@s.whatsapp.net`) so variants compare equal. */
+export function normalizeJid(jid: string): string {
+  try {
+    return jidNormalizedUser(jid) || jid;
+  } catch {
+    return jid;
+  }
+}
+
+export interface CanonicalJid {
+  /** The identity to use everywhere downstream. */
+  canonical: string;
+  /** The normalized input jid (differs from canonical when a mapping applied). */
+  original: string;
+  changed: boolean;
+}
+
+function unchanged(jid: string): CanonicalJid {
+  return { canonical: jid, original: jid, changed: false };
+}
+
+/**
+ * Synchronous canonicalization: key alt field + alias store only.
+ * Learns the pair whenever the key carries both forms. Never throws —
+ * a malformed key must never crash the Baileys message loop.
+ */
+export function canonicalizeJidSync(
+  rawJid: string | null | undefined,
+  altJid: string | null | undefined,
+  aliasStore?: WaAliasStore,
+): CanonicalJid {
+  if (!rawJid) return unchanged(rawJid ?? "");
+  try {
+    const raw = normalizeJid(rawJid);
+    const alt = altJid ? normalizeJid(altJid) : undefined;
+
+    if (!isLidJid(raw)) {
+      // Already canonical. If the key also carries the LID form, learn it so
+      // future LID-tagged messages resolve even without an alt field.
+      if (isPnJid(raw) && alt && isLidJid(alt)) {
+        aliasStore?.learn(alt, raw, "key-alt");
+      }
+      return unchanged(raw);
+    }
+
+    if (alt && isPnJid(alt)) {
+      aliasStore?.learn(raw, alt, "key-alt");
+      return { canonical: alt, original: raw, changed: true };
+    }
+
+    const mapped = aliasStore?.getPnForLid(raw);
+    if (mapped && isPnJid(mapped)) {
+      return { canonical: normalizeJid(mapped), original: raw, changed: true };
+    }
+
+    return unchanged(raw);
+  } catch {
+    return unchanged(rawJid);
+  }
+}
+
+/**
+ * Full canonicalization: sync chain first, then Baileys' async LID store.
+ * `lidLookup` wraps `sock.signalRepository.lidMapping.getPNForLID`.
+ */
+export async function canonicalizeJid(
+  rawJid: string | null | undefined,
+  altJid: string | null | undefined,
+  aliasStore?: WaAliasStore,
+  lidLookup?: (lid: string) => Promise<string | null>,
+): Promise<CanonicalJid> {
+  const sync = canonicalizeJidSync(rawJid, altJid, aliasStore);
+  if (sync.changed || !isLidJid(sync.canonical) || !lidLookup) return sync;
+
+  try {
+    const mapped = await lidLookup(sync.canonical);
+    if (mapped && isPnJid(normalizeJid(mapped))) {
+      const pn = normalizeJid(mapped);
+      aliasStore?.learn(sync.canonical, pn, "lid-mapping");
+      return { canonical: pn, original: sync.canonical, changed: true };
+    }
+  } catch {
+    // Lookup failure degrades to the LID — never crash the message loop.
+  }
+  return sync;
+}
+
+/** The subset of a Baileys message key this module reads. */
+export interface WaKeyLike {
+  remoteJid?: string | null;
+  remoteJidAlt?: string | null;
+  participant?: string | null;
+  participantAlt?: string | null;
+}
+
+export interface ResolvedIdentities {
+  /** Canonical sender jid (participant in groups, chat peer in DMs). */
+  sender: CanonicalJid;
+  /** Canonical chat jid. Group jids (`@g.us`) are never rewritten. */
+  chat: CanonicalJid;
+}
+
+/**
+ * Resolve both identities on an inbound key, async (full chain).
+ * Group chat jids pass through untouched; group participants are
+ * canonicalized exactly like DM senders.
+ */
+export async function resolveKeyIdentities(
+  key: WaKeyLike,
+  aliasStore?: WaAliasStore,
+  lidLookup?: (lid: string) => Promise<string | null>,
+): Promise<ResolvedIdentities> {
+  const remoteJid = key.remoteJid ?? "";
+  const isGroup = remoteJid.endsWith("@g.us");
+
+  const chat = isGroup
+    ? unchanged(remoteJid)
+    : await canonicalizeJid(remoteJid, key.remoteJidAlt, aliasStore, lidLookup);
+
+  const sender = key.participant
+    ? await canonicalizeJid(
+        key.participant,
+        key.participantAlt,
+        aliasStore,
+        lidLookup,
+      )
+    : chat;
+
+  return { sender, chat };
+}
+
+/** Sync variant of {@link resolveKeyIdentities} (key alts + alias store only). */
+export function resolveKeyIdentitiesSync(
+  key: WaKeyLike,
+  aliasStore?: WaAliasStore,
+): ResolvedIdentities {
+  const remoteJid = key.remoteJid ?? "";
+  const isGroup = remoteJid.endsWith("@g.us");
+
+  const chat = isGroup
+    ? unchanged(remoteJid)
+    : canonicalizeJidSync(remoteJid, key.remoteJidAlt, aliasStore);
+
+  const sender = key.participant
+    ? canonicalizeJidSync(key.participant, key.participantAlt, aliasStore)
+    : chat;
+
+  return { sender, chat };
+}

package/src/adapters/whatsapp.ts

@@ -30,6 +30,13 @@ import {
 import { logger } from "../logger.js";
 import { normalizeChatMarkdown } from "../text/markdown.js";
 import { applyRtlDirection } from "../text/rtl.js";
+import {
+  canonicalizeJidSync,
+  resolveKeyIdentities,
+  resolveKeyIdentitiesSync,
+  type WaAliasStore,
+  type WaKeyLike,
+} from "./whatsapp-identity.js";
 import { detectWhatsAppMedia } from "./whatsapp-media.js";
 
 type WhatsAppThreadId = {
@@ -68,12 +75,15 @@ function getContextInfo(
 function buildReplyContext(
   message?: proto.IMessage | null,
   pushNames?: Map<string, string>,
+  canonicalize?: (jid: string) => string,
 ): string | undefined {
   const contextInfo = getContextInfo(message);
   if (!contextInfo?.quotedMessage) return undefined;
 
   const quotedText = extractText(contextInfo.quotedMessage).trim();
-  const quotedJid = contextInfo.participant || "unknown";
+  const rawQuotedJid = contextInfo.participant || "unknown";
+  // pushNames is keyed by canonical jid — resolve before lookup.
+  const quotedJid = canonicalize ? canonicalize(rawQuotedJid) : rawQuotedJid;
   const quotedName =
     pushNames?.get(quotedJid) || quotedJid.split("@")[0] || "unknown";
   const quotedMessageId = contextInfo.stanzaId || "unknown";
@@ -131,6 +141,7 @@ export type WhatsAppQrStatus =
 export interface WhatsAppAdapterOptions {
   userName?: string;
   authDir?: string;
+  aliasStore?: WaAliasStore;
 }
 
 export class WhatsAppBaileysAdapter
@@ -154,12 +165,27 @@ export class WhatsAppBaileysAdapter
   /** Called when the bot is removed or leaves a WhatsApp group. */
   onGroupRemoval?: (chatJid: string) => void;
 
+  /** Persistent LID↔phone alias store — assigned by main.ts after core init. */
+  aliasStore?: WaAliasStore;
+
   constructor(options?: WhatsAppAdapterOptions) {
     this.userName = options?.userName ?? "mercury";
     this.authDir =
       options?.authDir ?? path.join(process.cwd(), ".mercury", "whatsapp-auth");
+    this.aliasStore = options?.aliasStore;
   }
 
+  /** Async LID→phone lookup backed by Baileys' internal mapping store. */
+  private lidLookup = async (lid: string): Promise<string | null> => {
+    const store = this.sock?.signalRepository?.lidMapping;
+    if (!store) return null;
+    return (await store.getPNForLID(lid)) ?? null;
+  };
+
+  /** Sync canonicalization for jids outside the message key (quoted senders). */
+  private canonicalizeQuoted = (jid: string): string =>
+    canonicalizeJidSync(jid, undefined, this.aliasStore).canonical;
+
   /**
    * Get current QR status for API endpoint
    */
@@ -412,15 +438,22 @@ export class WhatsAppBaileysAdapter
 
   parseMessage(raw: proto.IWebMessageInfo): Message<proto.IWebMessageInfo> {
     const key = raw.key;
-    const remoteJid = key?.remoteJid ?? "unknown@s.whatsapp.net";
-    const sender = key?.participant || remoteJid;
+    // Canonicalize on the raw key — the placeholder fallback is applied only
+    // after resolution so it can never be learned as a real phone mapping.
+    const identities = resolveKeyIdentitiesSync({ ...key }, this.aliasStore);
+    const chatJid = identities.chat.canonical || "unknown@s.whatsapp.net";
+    const sender = identities.sender.canonical || chatJid;
     const senderName = raw.pushName || sender.split("@")[0] || "unknown";
     const baseText = extractText(raw.message).trim();
-    const replyContext = buildReplyContext(raw.message, this.pushNames);
+    const replyContext = buildReplyContext(
+      raw.message,
+      this.pushNames,
+      this.canonicalizeQuoted,
+    );
     const text = [baseText, replyContext].filter(Boolean).join("\n\n").trim();
     const threadId = this.encodeThreadId({
-      chatJid: remoteJid,
-      threadJid: remoteJid,
+      chatJid,
+      threadJid: chatJid,
     });
 
     return new Message({
@@ -493,7 +526,21 @@ export class WhatsAppBaileysAdapter
       return;
     }
 
-    const sender = msg.key.participant || remoteJid;
+    // Canonicalize identities (LID → phone) before anything downstream sees
+    // them: sender becomes callerId, DM chat jid becomes the thread/space key.
+    const identities = await resolveKeyIdentities(
+      msg.key as WaKeyLike,
+      this.aliasStore,
+      this.lidLookup,
+    );
+    const chatJid = identities.chat.canonical;
+    const sender = identities.sender.canonical;
+    if (identities.sender.changed || identities.chat.changed) {
+      logger.debug("WhatsApp identity canonicalized", {
+        sender: identities.sender,
+        chat: identities.chat,
+      });
+    }
     const senderName = msg.pushName || sender.split("@")[0] || "unknown";
 
     // Track push names for reply context resolution
@@ -502,7 +549,11 @@ export class WhatsAppBaileysAdapter
     }
 
     let baseText = extractText(msg.message).trim();
-    const replyContext = buildReplyContext(msg.message, this.pushNames);
+    const replyContext = buildReplyContext(
+      msg.message,
+      this.pushNames,
+      this.canonicalizeQuoted,
+    );
 
     // WhatsApp @-mentions embed JIDs in text (e.g. "@52669955764381").
     // Replace the bot's JID mention with the configured userName so trigger matching works.
@@ -548,12 +599,20 @@ export class WhatsAppBaileysAdapter
     if (!text && !hasMedia) return;
 
     const threadId = this.encodeThreadId({
-      chatJid: remoteJid,
-      threadJid: remoteJid,
+      chatJid,
+      threadJid: chatJid,
     });
+    // When the DM chat jid was canonicalized, expose the original identity's
+    // thread id so the core can adopt a space created under the old (LID) key.
+    const aliasThreadId = identities.chat.changed
+      ? this.encodeThreadId({
+          chatJid: identities.chat.original,
+          threadJid: identities.chat.original,
+        })
+      : undefined;
 
     logger.info("WhatsApp inbound", {
-      remoteJid,
+      remoteJid: chatJid,
       sender,
       isReply: Boolean(replyContext),
       isReplyToBot,
@@ -589,6 +648,7 @@ export class WhatsAppBaileysAdapter
           isReplyToBot,
           replyToMessageId: contextInfo?.stanzaId ?? undefined,
           platformMessageId: msg.key.id ?? undefined,
+          aliasThreadId,
         } as Record<string, unknown>),
       },
       attachments: [],

package/src/core/conversation.ts

@@ -38,6 +38,14 @@ function seedSpaceConfigIfAbsent(
   }
 }
 
+/** First jid of a `<chatJid>:<threadJid>` external id, as a callerId. */
+function callerIdFromExternalId(platform: string, externalId: string): string {
+  return `${platform}:${externalId.split(":")[0]}`;
+}
+
+/** Double-split pairs already warned about — once per process, not per message. */
+const warnedDoubleSplits = new Set<string>();
+
 export function resolveConversation(
   db: Db,
   platform: string,
@@ -46,6 +54,7 @@ export function resolveConversation(
   observedTitle?: string,
   autoSpace?: AutoSpaceConfig,
   authorName?: string,
+  aliasExternalId?: string,
 ): ConversationResolution | null {
   const conversation = db.ensureConversation(
     platform,
@@ -55,14 +64,76 @@ export function resolveConversation(
   );
 
   if (conversation.spaceId) {
+    // Pre-upgrade double split: this person also has a space under their old
+    // identity. The canonical space wins; surface both for manual cleanup.
+    if (
+      kind === "dm" &&
+      aliasExternalId &&
+      aliasExternalId !== externalId &&
+      !warnedDoubleSplits.has(`${platform}:${aliasExternalId}`)
+    ) {
+      const aliasConversation = db.findConversation(platform, aliasExternalId);
+      if (
+        aliasConversation?.spaceId &&
+        aliasConversation.spaceId !== conversation.spaceId
+      ) {
+        warnedDoubleSplits.add(`${platform}:${aliasExternalId}`);
+        logger.warn(
+          "dm-auto-space: same person has two spaces (canonical wins)",
+          {
+            platform,
+            canonicalExternalId: externalId,
+            canonicalSpaceId: conversation.spaceId,
+            aliasExternalId,
+            aliasSpaceId: aliasConversation.spaceId,
+          },
+        );
+      }
+    }
     return { conversation, spaceId: conversation.spaceId };
   }
 
+  // Sticky-space adoption: the same person previously appeared under another
+  // identity (e.g. a WhatsApp LID before its phone mapping was known) and a
+  // space already exists there. Link this conversation to that space instead
+  // of creating a fresh one, and carry per-user rows (roles, mutes, rate
+  // usage) over to the canonical caller id. Runs regardless of auto-space so
+  // manually linked conversations keep working too.
+  if (kind === "dm" && aliasExternalId && aliasExternalId !== externalId) {
+    const aliasConversation = db.findConversation(platform, aliasExternalId);
+    if (aliasConversation?.spaceId) {
+      const spaceId = aliasConversation.spaceId;
+      db.linkConversation(conversation.id, spaceId);
+      const migrated = db.migrateCallerId(
+        spaceId,
+        callerIdFromExternalId(platform, aliasExternalId),
+        callerIdFromExternalId(platform, externalId),
+      );
+      logger.info(
+        "dm-auto-space: adopted existing space for canonical identity",
+        {
+          platform,
+          externalId,
+          aliasExternalId,
+          spaceId,
+          migratedRoles: migrated.roles,
+          migratedMutes: migrated.mutes,
+        },
+      );
+      return { conversation: { ...conversation, spaceId }, spaceId };
+    }
+  }
+
   if (!autoSpace?.enabled || kind !== "dm") return null;
 
   const senderNormalized = normalizePhone(externalId);
+  const aliasNormalized = aliasExternalId
+    ? normalizePhone(aliasExternalId)
+    : undefined;
   const isAdmin = autoSpace.adminIds.some(
-    (n) => normalizePhone(n) === senderNormalized,
+    (n) =>
+      normalizePhone(n) === senderNormalized ||
+      (aliasNormalized !== undefined && normalizePhone(n) === aliasNormalized),
   );
 
   if (isAdmin) {

package/src/core/global-admin.ts

@@ -2,10 +2,23 @@
  * Check if a caller is a global admin (configured in mercury.yaml / env).
  * Global admins are identified by `config.admins` and `config.dmAutoSpaceAdminIds`.
  * Platform-specific ID prefixes, + signs, and @domain suffixes are normalized.
+ *
+ * WhatsApp callers arrive canonicalized to their phone JID, but older configs
+ * may still list the LID digits (or vice versa when no mapping was known at
+ * config time). When an alias lookup is provided, the caller's learned
+ * LID↔phone counterpart is matched against the configured ids too.
  */
+
+/** Subset of Db used to resolve WhatsApp LID↔phone pairs. */
+export interface WaAliasLookup {
+  getWaPnForLid(lid: string): string | null;
+  getWaLidForPn(pn: string): string | null;
+}
+
 export function isGlobalAdmin(
   callerId: string,
   config: { admins?: string; dmAutoSpaceAdminIds?: string },
+  aliases?: WaAliasLookup,
 ): boolean {
   const globalAdmins = [
     ...(config.admins
@@ -28,9 +41,20 @@ export function isGlobalAdmin(
       .replace(/^[+]+/, "")
       .replace(/@.*$/, "");
 
-  const callerNormalized = normalize(callerId);
+  const callerCandidates = new Set([normalize(callerId)]);
+
+  if (aliases) {
+    const jid = callerId.replace(/^[^:]+:/, "");
+    if (jid.endsWith("@s.whatsapp.net")) {
+      const lid = aliases.getWaLidForPn(jid);
+      if (lid) callerCandidates.add(normalize(lid));
+    } else if (jid.endsWith("@lid")) {
+      const pn = aliases.getWaPnForLid(jid);
+      if (pn) callerCandidates.add(normalize(pn));
+    }
+  }
 
   return globalAdmins.some(
-    (id) => id === callerId || normalize(id) === callerNormalized,
+    (id) => id === callerId || callerCandidates.has(normalize(id)),
   );
 }

package/src/core/handler.ts

@@ -168,6 +168,14 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
 
       const { externalId, isDM } = bridge.parseThread(threadId);
       const kind = inferConversationKind(bridge.platform, externalId, isDM);
+      // Adapters that canonicalize identities (WhatsApp LID→phone) expose the
+      // pre-canonicalization thread id so an existing space can be adopted.
+      const aliasThreadId = (
+        message.metadata as { aliasThreadId?: string } | undefined
+      )?.aliasThreadId;
+      const aliasExternalId = aliasThreadId
+        ? bridge.parseThread(aliasThreadId).externalId
+        : undefined;
       const resolution = resolveConversation(
         core.db,
         bridge.platform,
@@ -176,6 +184,7 @@ export function createMessageHandler(opts: MessageHandlerOptions) {
         undefined,
         autoSpaceConfig,
         message.author.userName ?? message.author.fullName,
+        aliasExternalId,
       );
 
       if (!resolution) {

package/src/core/routes/broadcast.ts

@@ -7,13 +7,13 @@ export const broadcast = new Hono<Env>();
 
 broadcast.post("/", async (c) => {
   const { callerId } = getAuth(c);
-  const { config, runtime } = getApiCtx(c);
+  const { config, db, runtime } = getApiCtx(c);
 
   if (!config.dmAutoSpaceEnabled) {
     return c.json({ error: "dm_auto_space is not enabled" }, 503);
   }
 
-  if (!isGlobalAdmin(callerId, config)) {
+  if (!isGlobalAdmin(callerId, config, db)) {
     logger.warn("Broadcast denied — caller is not a global admin", {
       callerId,
     });

package/src/core/routes/character.ts

@@ -11,7 +11,7 @@ character.get("/", (c) => {
   const { callerId } = getAuth(c);
   const { config, db } = getApiCtx(c);
 
-  if (!isGlobalAdmin(callerId, config)) {
+  if (!isGlobalAdmin(callerId, config, db)) {
     logger.warn("Character get denied — caller is not a global admin", {
       callerId,
     });
@@ -28,7 +28,7 @@ character.put("/", async (c) => {
   const { callerId } = getAuth(c);
   const { config, db } = getApiCtx(c);
 
-  if (!isGlobalAdmin(callerId, config)) {
+  if (!isGlobalAdmin(callerId, config, db)) {
     logger.warn("Character set denied — caller is not a global admin", {
       callerId,
     });
@@ -57,7 +57,7 @@ character.delete("/", (c) => {
   const { callerId } = getAuth(c);
   const { config, db } = getApiCtx(c);
 
-  if (!isGlobalAdmin(callerId, config)) {
+  if (!isGlobalAdmin(callerId, config, db)) {
     logger.warn("Character clear denied — caller is not a global admin", {
       callerId,
     });

package/src/core/routes/send.ts

@@ -13,9 +13,9 @@ export const send = new Hono<Env>();
 
 send.post("/", async (c) => {
   const { callerId } = getAuth(c);
-  const { config, runtime } = getApiCtx(c);
+  const { config, db, runtime } = getApiCtx(c);
 
-  if (!isGlobalAdmin(callerId, config)) {
+  if (!isGlobalAdmin(callerId, config, db)) {
     logger.warn("Direct send denied — caller is not a global admin", {
       callerId,
     });

package/src/main.ts

@@ -287,6 +287,14 @@ async function main() {
     bridges.whatsapp = new WhatsAppBridge(
       adapters.whatsapp as WhatsAppBaileysAdapter,
     );
+    (adapters.whatsapp as WhatsAppBaileysAdapter).aliasStore = {
+      getPnForLid: (lid) => core.db.getWaPnForLid(lid),
+      learn: (lid, pn, source) => {
+        if (core.db.learnWaAlias(lid, pn, source)) {
+          logger.info("WhatsApp identity alias learned", { lid, pn, source });
+        }
+      },
+    };
     (adapters.whatsapp as WhatsAppBaileysAdapter).onGroupRemoval = (
       chatJid,
     ) => {

package/src/storage/db.ts

@@ -214,6 +214,17 @@ export class Db {
         created_at INTEGER NOT NULL,
         updated_at INTEGER NOT NULL
       );
+
+      CREATE TABLE IF NOT EXISTS wa_identity_aliases (
+        lid TEXT PRIMARY KEY,
+        pn TEXT NOT NULL,
+        source TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_wa_aliases_pn
+      ON wa_identity_aliases(pn);
     `);
     this.ensureMessagesRunMetaColumn();
     this.ensureChatStateClearBoundaryColumn();
@@ -1588,6 +1599,102 @@ export class Db {
     }));
   }
 
+  // ─── WhatsApp Identity Aliases ────────────────────────────────────────
+
+  /**
+   * Upsert a learned LID↔phone pair. Returns true when the pair is new or
+   * changed (callers use this to log the learn exactly once).
+   */
+  learnWaAlias(lid: string, pn: string, source: string): boolean {
+    const now = Date.now();
+    const result = this.db
+      .query(
+        `INSERT INTO wa_identity_aliases(lid, pn, source, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(lid) DO UPDATE SET
+           pn = excluded.pn,
+           source = excluded.source,
+           updated_at = excluded.updated_at
+         WHERE wa_identity_aliases.pn != excluded.pn`,
+      )
+      .run(lid, pn, source, now, now);
+    return result.changes > 0;
+  }
+
+  getWaPnForLid(lid: string): string | null {
+    const row = this.db
+      .query("SELECT pn FROM wa_identity_aliases WHERE lid = ?")
+      .get(lid) as { pn: string } | null;
+    return row?.pn ?? null;
+  }
+
+  /** Most recently learned LID for a phone (a phone can map to several LIDs). */
+  getWaLidForPn(pn: string): string | null {
+    const row = this.db
+      .query(
+        `SELECT lid FROM wa_identity_aliases WHERE pn = ?
+         ORDER BY updated_at DESC, lid LIMIT 1`,
+      )
+      .get(pn) as { lid: string } | null;
+    return row?.lid ?? null;
+  }
+
+  /**
+   * Rewrite per-user rows in a space from one caller id to another
+   * (space adoption after identity canonicalization). Rows whose target
+   * already exists are dropped rather than duplicated.
+   */
+  migrateCallerId(
+    spaceId: string,
+    oldCallerId: string,
+    newCallerId: string,
+  ): { roles: number; mutes: number } {
+    if (oldCallerId === newCallerId) return { roles: 0, mutes: 0 };
+    const now = Date.now();
+    let roles = 0;
+    let mutes = 0;
+    const tx = this.db.transaction(() => {
+      roles = this.db
+        .query(
+          `UPDATE OR IGNORE space_roles
+           SET platform_user_id = ?, updated_at = ?
+           WHERE space_id = ? AND platform_user_id = ?`,
+        )
+        .run(newCallerId, now, spaceId, oldCallerId).changes;
+      this.db
+        .query(
+          "DELETE FROM space_roles WHERE space_id = ? AND platform_user_id = ?",
+        )
+        .run(spaceId, oldCallerId);
+
+      mutes = this.db
+        .query(
+          `UPDATE OR IGNORE mutes
+           SET platform_user_id = ?
+           WHERE space_id = ? AND platform_user_id = ?`,
+        )
+        .run(newCallerId, spaceId, oldCallerId).changes;
+      this.db
+        .query("DELETE FROM mutes WHERE space_id = ? AND platform_user_id = ?")
+        .run(spaceId, oldCallerId);
+
+      this.db
+        .query(
+          `UPDATE OR IGNORE daily_rate_usage
+           SET platform_user_id = ?, updated_at = ?
+           WHERE space_id = ? AND platform_user_id = ?`,
+        )
+        .run(newCallerId, now, spaceId, oldCallerId);
+      this.db
+        .query(
+          "DELETE FROM daily_rate_usage WHERE space_id = ? AND platform_user_id = ?",
+        )
+        .run(spaceId, oldCallerId);
+    });
+    tx();
+    return { roles, mutes };
+  }
+
   // ─── Daily Rate Usage ─────────────────────────────────────────────────
 
   checkAndIncrementDailyUsage(