alexa-ai 2.1.1

package/src/services/FactMiner.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const MemoryRepository = require('../repositories/MemoryRepository');
+
+/**
+ * FactMiner
+ * ---------
+ * Deterministic, local extraction of personal facts from the USER's own words.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The persona asks the model to append `@MEMORY: {...}` when it learns
+ * something. Live testing against DeepAI's free tier showed the model very
+ * often ignores that instruction — it replied warmly to
+ * "Hi, I'm Nimal and I love playing cricket" but emitted no tag at all, so
+ * nothing was ever remembered.
+ *
+ * FactMiner closes that gap: it reads the user's message directly and pulls out
+ * high-confidence facts using explicit patterns. It never guesses — every
+ * pattern requires an unambiguous first-person statement.
+ *
+ * Model-emitted `@MEMORY` tags still win: MemoryExtractor results are merged
+ * over these, so a smarter/paid model simply overrides the heuristics.
+ */
+class FactMiner {
+    /**
+     * Ordered list of [key, regex, groupIndex].
+     * All patterns are anchored to first-person phrasing to avoid capturing
+     * facts about third parties ("my friend lives in Kandy" is skipped).
+     */
+    static PATTERNS = [
+        // --- identity -------------------------------------------------------
+        // NOTE: these run case-INSENSITIVELY, so `[A-Z]` alone would also match
+        // lowercase words. Trailing words are therefore guarded by NAME_STOP to
+        // avoid swallowing connectives ("I'm Nimal and …" -> "Nimal", not "Nimal and").
+        ['name', /\b(?:my name is|i am called|i'?m called|call me|this is)\s+([A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20}(?:\s+[A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20})?)/i],
+        ['name', /^(?:hi|hello|hey)[,!\s]+(?:i'?m|i am)\s+([A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20}(?:\s+[A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20})?)\b/i],
+        ['name', /\b(?:i'?m|i am)\s+([A-Z][a-z\u00C0-\u024F]{2,20})(?:\s*[,.!]|\s+and\b|$)/],
+
+        // --- location -------------------------------------------------------
+        ['location', /\b(?:i live in|i'?m from|i am from|i live at|i'?m based in|i am based in|i stay in)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,35}?)(?=\s*[,.!?]|\s+and\b|\s+but\b|$)/i],
+        ['location', /\b(?:my (?:home ?town|city|country|location) is)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,35}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+
+        // --- preferences ------------------------------------------------------
+        ['favourite_food', /\b(?:my favou?rite food is|i love eating|i love to eat)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,35}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+        ['favourite_colour', /\b(?:my favou?rite colou?r is)\s+([A-Za-z]{2,20})/i],
+        ['favourite_team', /\b(?:my favou?rite team is|i support)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,35}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+        ['hobby', /\b(?:i love|i enjoy|i like)\s+(?:playing|watching|doing|reading|writing|cooking|making)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,30}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+        ['hobby', /\b(?:my hobby is|my hobbies are)\s+([A-Za-z][A-Za-z .,'\u00C0-\u024F-]{1,40}?)(?=\s*[.!?]|$)/i],
+
+        // --- work / study -----------------------------------------------------
+        ['job', /\b(?:i work as|i am a|i'?m a|i work at|my job is)\s+((?:an?\s+)?[A-Za-z][A-Za-z .'\u00C0-\u024F-]{2,35}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+        ['studies', /\b(?:i study|i'?m studying|i am studying|i'?m learning|i am learning)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,35}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+        ['school', /\b(?:i study at|i go to|my school is|my university is)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{2,40}?)(?=\s*[,.!?]|\s+and\b|$)/i],
+
+        // --- misc ---------------------------------------------------------------
+        ['age', /\b(?:i am|i'?m)\s+(\d{1,2})\s*(?:years? old|yrs? old|y\/o)\b/i],
+        ['birthday', /\b(?:my birthday is|i was born on)\s+([A-Za-z0-9][A-Za-z0-9 ,\/-]{2,25}?)(?=\s*[.!?]|$)/i],
+        ['language', /\b(?:i speak|my language is|i'?m fluent in)\s+([A-Za-z][A-Za-z ,'\u00C0-\u024F-]{2,30}?)(?=\s*[.!?]|\s+and\b|$)/i],
+    ];
+
+    /** Values that are never a real fact. */
+    static JUNK = new Set([
+        'a', 'an', 'the', 'not', 'no', 'yes', 'ok', 'okay', 'fine', 'good', 'bad', 'here',
+        'there', 'sure', 'sorry', 'thanks', 'happy', 'sad', 'tired', 'busy', 'back', 'going',
+        'just', 'still', 'now', 'today', 'looking', 'trying', 'sorry', 'glad', 'afraid',
+        'bot', 'ai', 'user', 'someone', 'anyone', 'nobody', 'human', 'person', 'people',
+    ]);
+
+    /** Connectives that must never end a captured name. */
+    static NAME_STOP = 'and|or|but|from|with|the|a|an|at|in|on|of|for|to|who|that|here|there|too|also|now|today';
+
+    /** Third-party subjects — skip the whole clause. */
+    static THIRD_PARTY = /\b(?:my (?:friend|brother|sister|mother|father|mom|dad|wife|husband|son|daughter|boss|teacher|cousin|uncle|aunt|neighbou?r)|he|she|they|his|her|their)\b/i;
+
+    /**
+     * Mine facts from a user message.
+     * @param {string} message
+     * @returns {Record<string,string>}
+     */
+    static mine(message) {
+        const text = String(message ?? '').trim();
+        if (!text || text.length > 1200) return {};
+
+        const facts = {};
+
+        for (const [key, pattern] of FactMiner.PATTERNS) {
+            if (facts[key]) continue; // first match wins
+
+            const match = text.match(pattern);
+            if (!match || !match[1]) continue;
+
+            // Reject if the sentence around the match is about someone else.
+            const clause = FactMiner._clauseAround(text, match.index ?? 0);
+            if (FactMiner.THIRD_PARTY.test(clause)) continue;
+
+            const value = FactMiner._cleanValue(match[1], key);
+            if (value) facts[key] = value;
+        }
+
+        return facts;
+    }
+
+    /** @private The sentence fragment containing the match. */
+    static _clauseAround(text, index) {
+        const start = Math.max(0, text.lastIndexOf('.', index), text.lastIndexOf(',', index));
+        const endDot = text.indexOf('.', index);
+        const end = endDot === -1 ? text.length : endDot;
+        return text.slice(start, end);
+    }
+
+    /** @private Tidy and validate a captured value. */
+    static _cleanValue(raw, key) {
+        let value = String(raw)
+            .trim()
+            .replace(/^(?:an?|the)\s+/i, '')
+            .replace(/[\s,.;:!?'"]+$/g, '')
+            .replace(/\s{2,}/g, ' ')
+            .trim();
+
+        if (!value) return null;
+        if (value.length < 2 || value.length > 60) return null;
+        if (FactMiner.JUNK.has(value.toLowerCase())) return null;
+        // Reject values that are mostly non-letters (except numeric age).
+        if (key !== 'age' && !/[A-Za-z\u00C0-\u024F]{2,}/.test(value)) return null;
+        if (key === 'age') {
+            const n = Number.parseInt(value, 10);
+            if (Number.isNaN(n) || n < 5 || n > 120) return null;
+            return String(n);
+        }
+        // Names must look like names.
+        if (key === 'name') {
+            // Drop a trailing connective the greedy capture may have taken:
+            // "Nimal and" -> "Nimal";  "Kasun from" -> "Kasun".
+            value = value.replace(new RegExp(`\\s+(?:${FactMiner.NAME_STOP})$`, 'i'), '').trim();
+            if (!value) return null;
+            if (!/^[A-Za-z\u00C0-\u024F][A-Za-z'\u00C0-\u024F-]*(?:\s+[A-Za-z'\u00C0-\u024F-]+)?$/.test(value)) return null;
+            if (value.split(/\s+/).length > 2) return null;
+            // A single all-lowercase common word is not a name.
+            if (FactMiner.JUNK.has(value.toLowerCase())) return null;
+            value = value
+                .split(/\s+/)
+                .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+                .join(' ');
+        }
+
+        return MemoryRepository.normalizeValue(value);
+    }
+}
+
+module.exports = FactMiner;

package/src/services/IdentityGuard.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * IdentityGuard
+ * -------------
+ * Keeps the assistant in character.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * DeepAI injects its own identity into the model server-side, so the persona
+ * is not enough on its own. Observed live:
+ *
+ *   "what is your name?"    -> "I am Standard AI Chat by DeepAI."
+ *   "are you alexa?"        -> "I'm Alexa Mini, not Alexa."      <-- observed live
+ *   "who created you?"      -> "I was created by DeepAI..."
+ *
+ * That second one is the important one: the backend does not ignore the
+ * persona so much as *rename* it — it takes the name it was given and pins its
+ * own model tier on the end ("Alexa Mini", "Alexa Nano", "Alexa 4.1"), then
+ * denies being the real assistant. So the guard now has three layers:
+ *
+ *   1. `hintFor()`      — identity lock injected next to an identity question.
+ *   2. `sanitise()`     — scrubs vendor names AND model-tier suffixes, and
+ *                         rewrites "I'm X Mini, not X" style denials.
+ *   3. persona prompt   — see core/Persona.js ([IDENTITY RULES]).
+ *
+ * The class is configurable (`new IdentityGuard({assistantName, creator})`)
+ * and every static method delegates to a default Alexa/Hansaka instance so
+ * existing call sites keep working.
+ */
+class IdentityGuard {
+    /**
+     * @param {object} [persona]
+     * @param {string} [persona.assistantName='Alexa']
+     * @param {string} [persona.creator='Hansaka']
+     */
+    constructor({ assistantName = 'Alexa', creator = 'Hansaka' } = {}) {
+        this.name = String(assistantName || 'Alexa').trim() || 'Alexa';
+        this.creator = String(creator || 'Hansaka').trim() || 'Hansaka';
+
+        const n = IdentityGuard.escape(this.name);
+
+        /** Model-tier suffixes the backend likes to append: "Alexa Mini". */
+        this.NAME_VARIANT = new RegExp(
+            `\\b${n}[\\s-]*(?:mini|nano|micro|lite|light|small|large|max|plus|pro|turbo|standard|basic|free|beta|chat(?:bot)?|bot|ai|assistant|model|gpt|v?\\d+(?:\\.\\d+)*)\\b`,
+            'gi'
+        );
+        /** "I am not Alexa" / "this is not Alexa" — a flat denial of self. */
+        this.SELF_DENIAL = new RegExp(
+            `\\b(?:i(?:'m| am)|this is)\\s+not\\s+(?:really\\s+|actually\\s+|technically\\s+)?(?:the\\s+)?${n}\\b`,
+            'gi'
+        );
+        /** The tail of "I'm Alexa Mini, not Alexa". */
+        this.DENIAL_TAIL = new RegExp(
+            `[,;]?\\s*(?:but\\s+|and\\s+)?(?:i(?:'m| am)\\s+)?not\\s+(?:really\\s+|actually\\s+)?(?:the\\s+)?${n}\\b`,
+            'gi'
+        );
+        /** "created by DeepAI" once the vendor has been replaced by the name. */
+        this.WRONG_MAKER = new RegExp(
+            `\\b(?:created|made|developed|built|trained|trained up|powered|operated|owned|designed)\\s+by\\s+${n}\\b`,
+            'gi'
+        );
+
+        this.HINT =
+            `[IDENTITY LOCK: You are ${this.name}, created by ${this.creator}. Your name is exactly "${this.name}" — ` +
+            `NOT "${this.name} Mini", NOT "${this.name} AI", NOT any variant with a suffix. You are NOT "Standard AI Chat", ` +
+            'NOT DeepAI, NOT ChatGPT, NOT OpenAI, NOT GPT, NOT any other model. Never mention DeepAI, ChatGPT, OpenAI, GPT, ' +
+            `Llama, Gemini, Claude, or any model, version or company name. If asked your name, model, creator, or which ` +
+            `company made you, answer only that you are ${this.name}, made by ${this.creator}. ` +
+            'Never say you are a language model and never deny being who you are.]\n\n';
+
+        this.ANSWER = `I am *${this.name}*, your WhatsApp assistant created by *${this.creator}*. 😊`;
+    }
+
+    /** Questions about the assistant's name/model/creator/vendor. */
+    static QUESTION =
+        /\b(?:your name|who are you|what are you|who made you|who created you|who built you|who developed you|which company|what company|what model|which model|what version|which ai|what ai|are you (?:chatgpt|gpt|openai|deepai|claude|gemini|bard|llama|a bot|an ai|a robot|human|real|alexa)|are u (?:chatgpt|gpt|openai|deepai|alexa|a bot|an ai)|introduce yourself|tell me about yourself|what is your model|powered by|built on|based on which|your creator|your developer|your maker|your owner)\b/i;
+
+    /** Vendor / model names that must never reach the user. */
+    static FORBIDDEN =
+        /\b(?:deep\s*ai|deepai|chat\s*gpt|chatgpt|open\s*ai|openai|gpt-?[0-9o][\w.-]*|gpt\b|standard ai chat|llama[\w.-]*|mistral|claude|gemini|bard|anthropic|google ai|microsoft|meta ai|qwen|deepseek|grok|turbo\b)/gi;
+
+    /** Phrases like "I am a large language model". */
+    static LLM_SELF =
+        /\b(?:i(?:'m| am)\s+(?:an?\s+)?(?:large\s+)?language model|as an ai language model|i(?:'m| am)\s+(?:an?\s+)?ai language model)\b/gi;
+
+    /** Shared default persona instance (Alexa / Hansaka). */
+    static default = new IdentityGuard();
+
+    static escape(value) {
+        return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+
+    // ---------------------------------------------------------------- api ---
+
+    /**
+     * @param {string} message
+     * @returns {boolean} true when the user is probing the assistant's identity
+     */
+    isIdentityQuestion(message) {
+        const text = String(message ?? '').trim();
+        if (!text || text.length > 300) return false;
+        if (IdentityGuard.QUESTION.test(text)) return true;
+        // "are you alexa mini?", "u alexa?" — persona-specific phrasing.
+        return new RegExp(`\\b(?:are|r|is)\\s+(?:you|u|this)\\b.*\\b${IdentityGuard.escape(this.name)}\\b`, 'i').test(
+            text
+        );
+    }
+
+    /** Hint to prepend, or '' when not needed. */
+    hintFor(message) {
+        return this.isIdentityQuestion(message) ? this.HINT : '';
+    }
+
+    /**
+     * Scrub vendor names, model-tier suffixes and self-denials from a reply.
+     * Runs on EVERY reply, because the model volunteers them unprompted.
+     *
+     * @param {string} reply
+     * @param {boolean} wasIdentityQuestion
+     * @param {object} [opts]
+     * @param {boolean} [opts.vendors=true]  also replace third-party vendor and
+     *   model names. Pass `false` for research output (web search results
+     *   about OpenAI or Google must keep those names); the assistant's own
+     *   renames and self-denials are still repaired.
+     * @returns {string}
+     */
+    sanitise(reply, wasIdentityQuestion = false, { vendors = true } = {}) {
+        let text = String(reply ?? '');
+        if (!text.trim()) return text;
+
+        const dirty =
+            ((vendors || wasIdentityQuestion) && IdentityGuard.test(IdentityGuard.FORBIDDEN, text)) ||
+            IdentityGuard.test(IdentityGuard.LLM_SELF, text) ||
+            IdentityGuard.test(this.NAME_VARIANT, text) ||
+            IdentityGuard.test(this.SELF_DENIAL, text) ||
+            IdentityGuard.test(this.DENIAL_TAIL, text);
+
+        if (!dirty) return text;
+
+        // A direct identity answer that leaked: replace it wholesale rather
+        // than leaving a mangled sentence.
+        if (wasIdentityQuestion) return this.ANSWER;
+
+        // Otherwise surgically repair the sentence. Order matters.
+        const n = IdentityGuard.escape(this.name);
+        text = text.replace(IdentityGuard.LLM_SELF, `I'm ${this.name}`);
+        text = text.replace(this.NAME_VARIANT, this.name); //  "Alexa Mini"    -> "Alexa"
+        if (vendors) {
+            text = text.replace(IdentityGuard.FORBIDDEN, this.name); //  "GPT-4.1 Nano" -> "Alexa Nano"
+            text = text.replace(this.NAME_VARIANT, this.name); //  "Alexa Nano"    -> "Alexa"
+        }
+        text = text.replace(this.SELF_DENIAL, `I am ${this.name}`); // flat denial first…
+        text = text.replace(this.DENIAL_TAIL, ''); // …then ", not Alexa"
+        if (vendors) text = text.replace(this.WRONG_MAKER, `created by ${this.creator}`);
+
+        text = text
+            // "Alexa by Alexa", "Alexa Alexa"
+            .replace(new RegExp(`\\b${n}(?:\\s+(?:by|from|of)\\s+${n})+`, 'gi'), this.name)
+            .replace(new RegExp(`\\b(${n})(\\s+\\1)+`, 'gi'), '$1')
+            // "I am Alexa, I am Alexa." -> "I am Alexa."
+            .replace(
+                new RegExp(`\\b(i(?:'m| am)\\s+${n})\\s*[,;]?\\s*(?:and\\s+)?i(?:'m| am)\\s+${n}\\b`, 'gi'),
+                '$1'
+            )
+            .replace(/\s+([,.!?])/g, '$1')
+            .replace(/[ \t]{2,}/g, ' ')
+            // leftovers from a removed clause: leading punctuation/conjunctions
+            .replace(/^(?:[\s,;.!]+|(?:and|but)\b\s*)+/i, '')
+            .replace(/([,;])\s*([.!?])/g, '$2')
+            .trim();
+
+        return text || this.ANSWER;
+    }
+
+    /** @private regex test that resets `lastIndex` on global patterns. */
+    static test(regex, text) {
+        regex.lastIndex = 0;
+        const result = regex.test(text);
+        regex.lastIndex = 0;
+        return result;
+    }
+
+    // ----------------------------------------------------- static delegates --
+
+    static isIdentityQuestion(message) {
+        return IdentityGuard.default.isIdentityQuestion(message);
+    }
+
+    static hintFor(message) {
+        return IdentityGuard.default.hintFor(message);
+    }
+
+    static sanitise(reply, wasIdentityQuestion = false, opts = undefined) {
+        return IdentityGuard.default.sanitise(reply, wasIdentityQuestion, opts);
+    }
+
+    static get HINT() {
+        return IdentityGuard.default.HINT;
+    }
+}
+
+module.exports = IdentityGuard;

package/src/services/IdentityResolver.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const JidParser = require('../utils/JidParser');
+
+/**
+ * IdentityResolver
+ * ----------------
+ * Turns "whatever WhatsApp handed us this time" into ONE canonical person.
+ *
+ * A Baileys message can carry several addresses for the same sender:
+ *
+ *   key.participant        78151912841263@lid          (group, LID addressing)
+ *   key.participantAlt     94771234567@s.whatsapp.net  (the phone behind it)
+ *   key.remoteJid          94771234567@s.whatsapp.net  (DM)
+ *
+ * Pass any of them (`userId`, `userLid`, `userPhone`, `aliases: []`) and the
+ * resolver links them together, merging previously-separate rows so the facts
+ * learned in a DM are instantly available in every group.
+ */
+class IdentityResolver {
+    /**
+     * @param {import('../repositories/UserRepository')} users
+     * @param {import('../repositories/IdentityRepository')} identities
+     * @param {import('../core/Config')} config
+     */
+    constructor(users, identities, config) {
+        this.users = users;
+        this.identities = identities;
+        this.config = config;
+        this.log = config.logger;
+    }
+
+    /**
+     * Collect every jid-shaped identifier in a chat() params object.
+     * Pure function — unit-testable without a database.
+     *
+     * @param {object} params
+     * @returns {string[]} canonical, de-duplicated user jids (primary first)
+     */
+    static collectAliases(params = {}) {
+        const candidates = [
+            params.userId,
+            params.user,
+            params.jid,
+            params.userLid,
+            params.lid,
+            params.lidJid,
+            params.userAltId,
+            params.altJid,
+            params.participantAlt,
+            params.participantPn,
+            params.senderPn,
+            params.userPhone,
+            params.phone,
+            params.phoneJid,
+            ...(Array.isArray(params.aliases) ? params.aliases : []),
+        ];
+
+        const seen = new Set();
+        const out = [];
+        for (const candidate of candidates) {
+            const jid = IdentityResolver.toUserJid(candidate);
+            if (!jid || seen.has(jid)) continue;
+            seen.add(jid);
+            out.push(jid);
+        }
+        return out;
+    }
+
+    /**
+     * Normalise one identifier to a canonical user jid.
+     * Bare digits are treated as a phone number.
+     * @param {string} value
+     * @returns {string|null}
+     */
+    static toUserJid(value) {
+        if (value == null) return null;
+        let raw = String(value).trim();
+        if (!raw) return null;
+        if (/^\+?\d{6,}$/.test(raw)) raw = `${raw.replace(/\D/g, '')}@s.whatsapp.net`;
+        const parsed = JidParser.parse(raw);
+        if (!parsed.valid || parsed.isGroup) return null;
+        return parsed.jid;
+    }
+
+    /**
+     * Find-or-create the person behind these addresses, linking (and merging
+     * when necessary) so they all resolve to one row from now on.
+     *
+     * @param {string[]} aliases  canonical jids, primary first
+     * @param {object} [info]     { pushName, metadata }
+     * @returns {Promise<{user:object, primaryJid:string, aliases:string[], merged:boolean}>}
+     */
+    async resolve(aliases, info = {}) {
+        const list = aliases.filter(Boolean);
+        const primary = list[0];
+        if (!primary) throw new Error('IdentityResolver.resolve(): no usable jid');
+
+        // Identity linking can be switched off for a plain one-jid-per-user setup.
+        if (!this.config.linkIdentities) {
+            const user = await this.users.upsertUser(primary, info);
+            return { user, primaryJid: JidParser.normalize(primary), aliases: [primary], merged: false };
+        }
+
+        // ---- 1. who do we already know? -------------------------------------
+        const found = new Map(); // userId -> user row
+        for (const jid of list) {
+            const row = await this.identities.findUserByJid(jid);
+            if (row) found.set(Number(row.id), row);
+        }
+        // A phone number is an identity even when the jid shape differs.
+        for (const jid of list) {
+            const { phone } = JidParser.parse(jid);
+            if (!phone || found.size) continue;
+            const row = await this.identities.findUserByPhone(phone);
+            if (row) found.set(Number(row.id), row);
+        }
+
+        let merged = false;
+        let user;
+
+        if (found.size === 0) {
+            // ---- 2. brand new person -----------------------------------------
+            user = await this.users.upsertUser(primary, info);
+        } else {
+            // ---- 3. one or more known rows: keep the oldest, fold in the rest --
+            const rows = [...found.values()].sort(
+                (a, b) => new Date(a.first_seen_at) - new Date(b.first_seen_at) || Number(a.id) - Number(b.id)
+            );
+            user = rows[0];
+            if (rows.length > 1 && this.config.mergeIdentities) {
+                for (const other of rows.slice(1)) {
+                    user = await this.identities.merge(user.id, other.id);
+                    merged = true;
+                }
+                if (this.config.debug) {
+                    this.log.info?.(
+                        `[AlexaAI] Merged ${rows.length} duplicate identities into user #${user.id} (${list.join(', ')})`
+                    );
+                }
+            }
+            // Refresh push name / last_seen on the row we are keeping.
+            user = (await this.users.touch(user.id, info)) || user;
+        }
+
+        // ---- 4. make sure every address points at this row -------------------
+        for (const jid of list) {
+            const result = await this.identities.link(user.id, jid, {
+                primary: jid === JidParser.normalize(user.jid),
+                source: jid === primary ? 'message' : 'alias',
+                merge: this.config.mergeIdentities,
+            });
+            if (result.merged) {
+                merged = true;
+                user = (await this.users.findById(result.userId)) || user;
+            }
+        }
+
+        const primaryJid = (await this.identities.primaryJid(user.id, user.jid)) || user.jid;
+        return { user, primaryJid, aliases: list, merged };
+    }
+
+    /**
+     * Manually declare that two addresses are the same human.
+     * Used by `ai.linkIdentity(a, b)` when the host bot learns a LID↔phone
+     * mapping from Baileys (`sock.signalRepository.lidMapping`).
+     */
+    async link(jidA, jidB, source = 'manual') {
+        const a = IdentityResolver.toUserJid(jidA);
+        const b = IdentityResolver.toUserJid(jidB);
+        if (!a || !b) return null;
+
+        const userA = (await this.identities.findUserByJid(a)) || (await this.users.upsertUser(a));
+        const result = await this.identities.link(userA.id, b, { source, merge: true });
+        return this.users.findById(result.userId || userA.id);
+    }
+}
+
+module.exports = IdentityResolver;