alexa-ai 2.1.1

package/src/db/schema.sql

@@ -0,0 +1,214 @@
+-- ============================================================================
+--  Alexa AI — PostgreSQL schema
+--  Safe to run repeatedly (idempotent).
+--
+--  Identity model
+--  --------------
+--  WhatsApp gives us two independent identifiers:
+--     user  : 78151912841263@lid   or  94771234567@s.whatsapp.net
+--     group : 120363413125431525@g.us
+--
+--  A user is ONE row in wa_users keyed by their jid. That row is shared across
+--  every group and the DM, so "recognise user data in any group" works by
+--  construction: memories hang off user_id, never off the group.
+--
+--  Conversations are separate threads (DM vs each group) so chat context never
+--  bleeds between rooms, while the user's identity and memories stay global.
+-- ============================================================================
+
+-- ---------------------------------------------------------------- users -----
+CREATE TABLE IF NOT EXISTS wa_users (
+    id              BIGSERIAL PRIMARY KEY,
+    jid             TEXT        NOT NULL UNIQUE,            -- canonical: 78151912841263@lid
+    jid_local       TEXT        NOT NULL,                   -- 78151912841263
+    jid_server      TEXT        NOT NULL,                   -- lid | s.whatsapp.net
+    jid_type        TEXT        NOT NULL DEFAULT 'user',    -- lid | user
+    phone           TEXT,                                   -- NULL for @lid (privacy id)
+    push_name       TEXT,                                   -- WhatsApp display name
+    display_name    TEXT,                                   -- name Alexa learned/prefers
+    is_blocked      BOOLEAN     NOT NULL DEFAULT FALSE,
+    is_admin        BOOLEAN     NOT NULL DEFAULT FALSE,
+    locale          TEXT,
+    message_count   BIGINT      NOT NULL DEFAULT 0,
+    token_estimate  BIGINT      NOT NULL DEFAULT 0,
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    first_seen_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_users_phone      ON wa_users (phone) WHERE phone IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_wa_users_last_seen  ON wa_users (last_seen_at DESC);
+CREATE INDEX IF NOT EXISTS idx_wa_users_local      ON wa_users (jid_local);
+
+-- ----------------------------------------------------- user identities ------
+-- WhatsApp hands the SAME human different jids depending on where they write:
+--   DM      : 94771234567@s.whatsapp.net   (phone number jid)
+--   Group   : 78151912841263@lid           (privacy / LID jid)
+-- Without a mapping the bot creates two rows and "forgets" the user the moment
+-- they speak in a group. Every jid a person is ever seen under is recorded
+-- here and points at ONE wa_users row, so memories follow the human, not the
+-- address they happen to be using.
+CREATE TABLE IF NOT EXISTS wa_user_identities (
+    id              BIGSERIAL PRIMARY KEY,
+    user_id         BIGINT      NOT NULL REFERENCES wa_users(id) ON DELETE CASCADE,
+    jid             TEXT        NOT NULL UNIQUE,            -- 78151912841263@lid
+    jid_local       TEXT        NOT NULL,
+    jid_server      TEXT        NOT NULL,
+    jid_type        TEXT        NOT NULL DEFAULT 'user',    -- lid | user
+    phone           TEXT,                                   -- NULL for @lid
+    is_primary      BOOLEAN     NOT NULL DEFAULT FALSE,
+    source          TEXT,                                   -- how the link was learned
+    first_seen_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_identities_user  ON wa_user_identities (user_id);
+CREATE INDEX IF NOT EXISTS idx_wa_identities_phone ON wa_user_identities (phone) WHERE phone IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_wa_identities_local ON wa_user_identities (jid_local);
+
+-- Backfill: every existing user is their own primary identity.
+INSERT INTO wa_user_identities (user_id, jid, jid_local, jid_server, jid_type, phone, is_primary, source)
+SELECT u.id, u.jid, u.jid_local, u.jid_server, u.jid_type, u.phone, TRUE, 'backfill'
+  FROM wa_users u
+ WHERE NOT EXISTS (SELECT 1 FROM wa_user_identities i WHERE i.jid = u.jid);
+
+-- --------------------------------------------------------------- groups -----
+CREATE TABLE IF NOT EXISTS wa_groups (
+    id              BIGSERIAL PRIMARY KEY,
+    jid             TEXT        NOT NULL UNIQUE,            -- 120363413125431525@g.us
+    subject         TEXT,                                   -- group title
+    description     TEXT,
+    is_enabled      BOOLEAN     NOT NULL DEFAULT TRUE,      -- AI on/off per group
+    message_count   BIGINT      NOT NULL DEFAULT 0,
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    first_seen_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_groups_last_seen ON wa_groups (last_seen_at DESC);
+
+-- ------------------------------------------------------- group membership ---
+-- Tracks which user was seen in which group (per-room stats, admin flags).
+-- Identity still lives in wa_users, so memories remain global.
+CREATE TABLE IF NOT EXISTS wa_group_members (
+    id              BIGSERIAL PRIMARY KEY,
+    group_id        BIGINT      NOT NULL REFERENCES wa_groups(id) ON DELETE CASCADE,
+    user_id         BIGINT      NOT NULL REFERENCES wa_users(id)  ON DELETE CASCADE,
+    is_admin        BOOLEAN     NOT NULL DEFAULT FALSE,
+    message_count   BIGINT      NOT NULL DEFAULT 0,
+    first_seen_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_seen_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (group_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_group_members_user ON wa_group_members (user_id);
+
+-- -------------------------------------------------------- conversations -----
+-- One row per thread. DM => group_id NULL. Group => (group_id, user_id).
+CREATE TABLE IF NOT EXISTS wa_conversations (
+    id              BIGSERIAL PRIMARY KEY,
+    context_key     TEXT        NOT NULL UNIQUE,            -- dm:<jid> | group:<gjid>:<ujid>
+    user_id         BIGINT      REFERENCES wa_users(id)  ON DELETE CASCADE,
+    group_id        BIGINT      REFERENCES wa_groups(id) ON DELETE CASCADE,
+    kind            TEXT        NOT NULL DEFAULT 'dm',      -- dm | group
+    title           TEXT,
+    message_count   BIGINT      NOT NULL DEFAULT 0,
+    last_message_at TIMESTAMPTZ,
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_conversations_user  ON wa_conversations (user_id);
+CREATE INDEX IF NOT EXISTS idx_wa_conversations_group ON wa_conversations (group_id);
+CREATE INDEX IF NOT EXISTS idx_wa_conversations_last  ON wa_conversations (last_message_at DESC NULLS LAST);
+
+-- ------------------------------------------------------------- messages -----
+CREATE TABLE IF NOT EXISTS wa_messages (
+    id              BIGSERIAL PRIMARY KEY,
+    conversation_id BIGINT      NOT NULL REFERENCES wa_conversations(id) ON DELETE CASCADE,
+    user_id         BIGINT      REFERENCES wa_users(id) ON DELETE SET NULL,
+    role            TEXT        NOT NULL CHECK (role IN ('user','assistant','system')),
+    content         TEXT        NOT NULL,
+    has_media       BOOLEAN     NOT NULL DEFAULT FALSE,
+    media_type      TEXT,
+    wa_message_id   TEXT,                                   -- WhatsApp msg id (dedupe)
+    tokens          INTEGER,
+    metadata        JSONB       NOT NULL DEFAULT '{}'::jsonb,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Primary read path: newest N messages of a thread.
+CREATE INDEX IF NOT EXISTS idx_wa_messages_convo_time
+    ON wa_messages (conversation_id, created_at DESC, id DESC);
+CREATE INDEX IF NOT EXISTS idx_wa_messages_user ON wa_messages (user_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_wa_messages_wa_id
+    ON wa_messages (conversation_id, wa_message_id) WHERE wa_message_id IS NOT NULL;
+
+-- ------------------------------------------------------------- memories -----
+-- Long-term facts, keyed to the USER (never the group) so Alexa recognises the
+-- same person in a DM and in every group. `key` is unique per user: re-learning
+-- "name" overwrites rather than duplicating.
+CREATE TABLE IF NOT EXISTS wa_memories (
+    id              BIGSERIAL PRIMARY KEY,
+    user_id         BIGINT      NOT NULL REFERENCES wa_users(id) ON DELETE CASCADE,
+    key             TEXT        NOT NULL,
+    value           TEXT        NOT NULL,
+    source          TEXT        NOT NULL DEFAULT 'auto',    -- auto | manual | import
+    confidence      REAL        NOT NULL DEFAULT 1.0,
+    hit_count       INTEGER     NOT NULL DEFAULT 0,         -- times injected into a prompt
+    learned_in      TEXT,                                   -- context_key where learned
+    expires_at      TIMESTAMPTZ,                            -- NULL = permanent
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (user_id, key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_memories_user    ON wa_memories (user_id, updated_at DESC);
+CREATE INDEX IF NOT EXISTS idx_wa_memories_expires ON wa_memories (expires_at) WHERE expires_at IS NOT NULL;
+
+-- ---------------------------------------------------------------- audit ------
+CREATE TABLE IF NOT EXISTS wa_ai_usage (
+    id              BIGSERIAL PRIMARY KEY,
+    user_id         BIGINT      REFERENCES wa_users(id) ON DELETE SET NULL,
+    conversation_id BIGINT      REFERENCES wa_conversations(id) ON DELETE SET NULL,
+    model           TEXT,
+    ok              BOOLEAN     NOT NULL DEFAULT TRUE,
+    error_code      TEXT,
+    latency_ms      INTEGER,
+    prompt_chars    INTEGER,
+    reply_chars     INTEGER,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_wa_ai_usage_time ON wa_ai_usage (created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_wa_ai_usage_user ON wa_ai_usage (user_id);
+
+-- --------------------------------------------------- updated_at triggers -----
+CREATE OR REPLACE FUNCTION wa_touch_updated_at() RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = NOW();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DO $$
+DECLARE t TEXT;
+BEGIN
+    FOREACH t IN ARRAY ARRAY['wa_users','wa_groups','wa_conversations','wa_memories']
+    LOOP
+        IF NOT EXISTS (
+            SELECT 1 FROM pg_trigger
+            WHERE tgname = 'trg_touch_' || t
+        ) THEN
+            EXECUTE format(
+                'CREATE TRIGGER trg_touch_%1$s BEFORE UPDATE ON %1$s
+                 FOR EACH ROW EXECUTE FUNCTION wa_touch_updated_at()', t);
+        END IF;
+    END LOOP;
+END;
+$$;

package/src/repositories/ConversationRepository.js

@@ -0,0 +1,206 @@
+'use strict';
+
+const JidParser = require('../utils/JidParser');
+
+/**
+ * ConversationRepository
+ * ----------------------
+ * Threads and their messages.
+ *
+ * A DM and each group are separate threads so chat context never leaks between
+ * rooms — while user identity/memory stays global (see MemoryRepository).
+ */
+class ConversationRepository {
+    /** @param {import('../db/Database')} db */
+    constructor(db) {
+        this.db = db;
+    }
+
+    /**
+     * Find-or-create the thread for this (user, group) pair.
+     * @param {object} params
+     * @param {string} params.contextKey
+     * @param {number} params.userId
+     * @param {number|null} [params.groupId]
+     * @param {string} [params.title]
+     * @returns {Promise<object>}
+     */
+    async upsertConversation({ contextKey, userId, groupId = null, title = null }) {
+        const kind = groupId ? 'group' : 'dm';
+        return this.db.one(
+            `INSERT INTO wa_conversations (context_key, user_id, group_id, kind, title)
+             VALUES ($1, $2, $3, $4, $5)
+             ON CONFLICT (context_key) DO UPDATE
+               SET updated_at = NOW(),
+                   title      = COALESCE(EXCLUDED.title, wa_conversations.title)
+             RETURNING *`,
+            [contextKey, userId, groupId, kind, title]
+        );
+    }
+
+    /**
+     * Append a message.
+     * @param {object} params
+     * @param {number} params.conversationId
+     * @param {number|null} params.userId
+     * @param {'user'|'assistant'|'system'} params.role
+     * @param {string} params.content
+     * @param {boolean} [params.hasMedia]
+     * @param {string} [params.mediaType]
+     * @param {string} [params.waMessageId]
+     * @param {object} [params.metadata]
+     * @returns {Promise<object|null>} null when deduped
+     */
+    async addMessage({
+        conversationId,
+        userId = null,
+        role,
+        content,
+        hasMedia = false,
+        mediaType = null,
+        waMessageId = null,
+        metadata = {},
+    }) {
+        const text = String(content ?? '');
+        if (!conversationId || !text.trim()) return null;
+
+        // ON CONFLICT DO NOTHING relies on the partial unique index over
+        // (conversation_id, wa_message_id) — WhatsApp redelivers on reconnect.
+        const row = await this.db.one(
+            `INSERT INTO wa_messages
+                 (conversation_id, user_id, role, content, has_media, media_type, wa_message_id, tokens, metadata)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb)
+             ON CONFLICT DO NOTHING
+             RETURNING *`,
+            [
+                conversationId,
+                userId,
+                role,
+                text,
+                Boolean(hasMedia),
+                mediaType,
+                waMessageId,
+                Math.ceil(text.length / 4),
+                JSON.stringify(metadata || {}),
+            ]
+        );
+
+        if (row) {
+            await this.db.query(
+                `UPDATE wa_conversations
+                    SET message_count   = message_count + 1,
+                        last_message_at = NOW(),
+                        updated_at      = NOW()
+                  WHERE id = $1`,
+                [conversationId]
+            );
+        }
+        return row;
+    }
+
+    /**
+     * Newest `limit` messages in chronological order, ready for the model.
+     * @param {number} conversationId
+     * @param {number} [limit=14]
+     * @returns {Promise<Array<{role:string, content:string}>>}
+     */
+    async getHistory(conversationId, limit = 14) {
+        if (!conversationId) return [];
+        const rows = await this.db.many(
+            `SELECT role, content, created_at
+               FROM (
+                   SELECT role, content, created_at, id
+                     FROM wa_messages
+                    WHERE conversation_id = $1
+                      AND role IN ('user','assistant')
+                    ORDER BY created_at DESC, id DESC
+                    LIMIT $2
+               ) recent
+              ORDER BY created_at ASC, id ASC`,
+            [conversationId, limit]
+        );
+        return rows.map((r) => ({ role: r.role, content: r.content }));
+    }
+
+    async findByContextKey(contextKey) {
+        return this.db.one('SELECT * FROM wa_conversations WHERE context_key = $1', [contextKey]);
+    }
+
+    /** Wipe a thread's messages (keeps the user and their memories). */
+    async clearHistory(contextKey) {
+        const convo = await this.findByContextKey(contextKey);
+        if (!convo) return 0;
+        const { rowCount } = await this.db.query('DELETE FROM wa_messages WHERE conversation_id = $1', [
+            convo.id,
+        ]);
+        await this.db.query(
+            'UPDATE wa_conversations SET message_count = 0, last_message_at = NULL WHERE id = $1',
+            [convo.id]
+        );
+        return rowCount;
+    }
+
+    /**
+     * Trim a thread to its newest `keep` messages.
+     * Called opportunistically so tables stay bounded on busy groups.
+     */
+    async trim(conversationId, keep = 200) {
+        if (!conversationId) return 0;
+        const { rowCount } = await this.db.query(
+            `DELETE FROM wa_messages
+              WHERE conversation_id = $1
+                AND id NOT IN (
+                    SELECT id FROM wa_messages
+                     WHERE conversation_id = $1
+                     ORDER BY created_at DESC, id DESC
+                     LIMIT $2
+                )`,
+            [conversationId, keep]
+        );
+        return rowCount;
+    }
+
+    /**
+     * All threads a user participates in (DM + every group).
+     * Accepts ANY address the person is known under, not just their canonical
+     * jid, so a group `@lid` finds the threads created from their DM.
+     */
+    async listForUser(rawJid) {
+        const jid = JidParser.normalize(rawJid);
+        return this.db.many(
+            `SELECT c.*, g.subject AS group_subject
+               FROM wa_conversations c
+               JOIN wa_users u ON u.id = c.user_id
+          LEFT JOIN wa_groups g ON g.id = c.group_id
+              WHERE u.jid = $1
+                 OR u.id = (SELECT user_id FROM wa_user_identities WHERE jid = $1)
+              ORDER BY c.last_message_at DESC NULLS LAST`,
+            [jid]
+        );
+    }
+
+    /** Audit row for observability. */
+    async logUsage({
+        userId = null,
+        conversationId = null,
+        model = null,
+        ok = true,
+        errorCode = null,
+        latencyMs = null,
+        promptChars = null,
+        replyChars = null,
+    }) {
+        try {
+            await this.db.query(
+                `INSERT INTO wa_ai_usage
+                     (user_id, conversation_id, model, ok, error_code, latency_ms, prompt_chars, reply_chars)
+                 VALUES ($1,$2,$3,$4,$5,$6,$7,$8)`,
+                [userId, conversationId, model, ok, errorCode, latencyMs, promptChars, replyChars]
+            );
+        } catch {
+            // Telemetry must never break a reply.
+        }
+    }
+}
+
+module.exports = ConversationRepository;

package/src/repositories/IdentityRepository.js

@@ -0,0 +1,244 @@
+'use strict';
+
+const JidParser = require('../utils/JidParser');
+const { ValidationError } = require('../core/errors');
+
+/**
+ * IdentityRepository
+ * ------------------
+ * The alias graph that makes "one human = one row" true.
+ *
+ * THE BUG THIS FIXES
+ * ------------------
+ * WhatsApp addresses the same person differently depending on the surface:
+ *
+ *   DM      -> 94771234567@s.whatsapp.net   (phone jid)
+ *   Group   -> 78151912841263@lid           (privacy jid, LID addressing)
+ *
+ * The engine used to key `wa_users` on the jid alone, so the person who
+ * introduced themselves in a DM was a *different* row in a group — and Alexa
+ * answered "sorry, as a bot I can't remember you". Now every jid a person is
+ * seen under is stored in `wa_user_identities` and resolves to one user id;
+ * when two rows turn out to be the same human they are merged, memories and
+ * transcripts included.
+ */
+class IdentityRepository {
+    /** @param {import('../db/Database')} db */
+    constructor(db) {
+        this.db = db;
+    }
+
+    /**
+     * The user a jid belongs to, following the alias graph.
+     * @param {string} rawJid
+     * @returns {Promise<object|null>} wa_users row
+     */
+    async findUserByJid(rawJid) {
+        const jid = JidParser.normalize(rawJid);
+        if (!jid) return null;
+        return this.db.one(
+            `SELECT u.* FROM wa_users u
+               JOIN wa_user_identities i ON i.user_id = u.id
+              WHERE i.jid = $1
+              LIMIT 1`,
+            [jid]
+        );
+    }
+
+    /** The user that owns a phone number, whatever jid shape it was seen as. */
+    async findUserByPhone(phone) {
+        const digits = String(phone || '').replace(/\D/g, '');
+        if (digits.length < 6) return null;
+        return this.db.one(
+            `SELECT u.* FROM wa_users u
+               JOIN wa_user_identities i ON i.user_id = u.id
+              WHERE i.phone = $1
+              ORDER BY i.is_primary DESC, i.first_seen_at ASC
+              LIMIT 1`,
+            [digits]
+        );
+    }
+
+    /** Every jid known for a user (primary first). */
+    async aliasesFor(userId) {
+        if (!userId) return [];
+        return this.db.many(
+            `SELECT jid, jid_type, phone, is_primary, source, last_seen_at
+               FROM wa_user_identities
+              WHERE user_id = $1
+              ORDER BY is_primary DESC, first_seen_at ASC`,
+            [userId]
+        );
+    }
+
+    /**
+     * Record `rawJid` as an alias of `userId`.
+     * If the jid already belongs to someone else the two users are merged
+     * (unless `merge:false`), because a jid can only ever be one human.
+     *
+     * @param {number} userId
+     * @param {string} rawJid
+     * @param {object} [opts]
+     * @param {boolean} [opts.primary=false]
+     * @param {string} [opts.source='observed']
+     * @param {boolean} [opts.merge=true]
+     * @returns {Promise<{linked:boolean, merged:boolean, userId:number}>}
+     */
+    async link(userId, rawJid, opts = {}) {
+        const parsed = JidParser.parse(rawJid);
+        if (!userId || !parsed.valid || parsed.isGroup) return { linked: false, merged: false, userId };
+
+        const existing = await this.db.one('SELECT * FROM wa_user_identities WHERE jid = $1', [parsed.jid]);
+
+        if (existing && Number(existing.user_id) !== Number(userId)) {
+            if (opts.merge === false) return { linked: false, merged: false, userId };
+            const keep = await this.merge(userId, existing.user_id);
+            return { linked: true, merged: true, userId: keep.id };
+        }
+
+        await this.db.query(
+            `INSERT INTO wa_user_identities (user_id, jid, jid_local, jid_server, jid_type, phone, is_primary, source)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+             ON CONFLICT (jid) DO UPDATE
+               SET user_id      = EXCLUDED.user_id,
+                   last_seen_at = NOW(),
+                   phone        = COALESCE(wa_user_identities.phone, EXCLUDED.phone),
+                   is_primary   = wa_user_identities.is_primary OR EXCLUDED.is_primary,
+                   source       = COALESCE(wa_user_identities.source, EXCLUDED.source)`,
+            [
+                userId,
+                parsed.jid,
+                parsed.local,
+                parsed.server,
+                parsed.type,
+                parsed.phone,
+                Boolean(opts.primary),
+                opts.source || 'observed',
+            ]
+        );
+
+        // A phone jid teaches us the person's number even when the row was
+        // first created from an anonymous @lid.
+        if (parsed.phone) {
+            await this.db.query('UPDATE wa_users SET phone = COALESCE(phone, $2) WHERE id = $1', [
+                userId,
+                parsed.phone,
+            ]);
+        }
+        return { linked: true, merged: false, userId };
+    }
+
+    /**
+     * Fold `loserId` into `winnerId`: memories, transcripts, group membership,
+     * usage rows and aliases all move across, then the loser row is deleted.
+     * The OLDER row always wins so the longest-lived history survives.
+     *
+     * @returns {Promise<object>} the surviving wa_users row
+     */
+    async merge(winnerId, loserId) {
+        const a = Number(winnerId);
+        const b = Number(loserId);
+        if (!a || !b) throw new ValidationError('merge() needs two user ids');
+        if (a === b) return this.db.one('SELECT * FROM wa_users WHERE id = $1', [a]);
+
+        const rows = await this.db.many('SELECT * FROM wa_users WHERE id = ANY($1::bigint[])', [[a, b]]);
+        if (rows.length < 2) {
+            return this.db.one('SELECT * FROM wa_users WHERE id = $1', [rows[0]?.id || a]);
+        }
+        const [older, newer] = rows.sort(
+            (x, y) => new Date(x.first_seen_at) - new Date(y.first_seen_at) || Number(x.id) - Number(y.id)
+        );
+        const keepId = Number(older.id);
+        const dropId = Number(newer.id);
+
+        return this.db.transaction(async (client) => {
+            // --- memories: newest value of each key wins -------------------
+            await client.query(
+                `DELETE FROM wa_memories k
+                  USING wa_memories d
+                  WHERE k.user_id = $1 AND d.user_id = $2
+                    AND k.key = d.key
+                    AND d.updated_at > k.updated_at`,
+                [keepId, dropId]
+            );
+            await client.query(
+                `UPDATE wa_memories SET user_id = $1
+                  WHERE user_id = $2
+                    AND key NOT IN (SELECT key FROM wa_memories WHERE user_id = $1)`,
+                [keepId, dropId]
+            );
+            await client.query('DELETE FROM wa_memories WHERE user_id = $1', [dropId]);
+
+            // --- group membership ------------------------------------------
+            await client.query(
+                `UPDATE wa_group_members SET user_id = $1
+                  WHERE user_id = $2
+                    AND group_id NOT IN (SELECT group_id FROM wa_group_members WHERE user_id = $1)`,
+                [keepId, dropId]
+            );
+            await client.query('DELETE FROM wa_group_members WHERE user_id = $1', [dropId]);
+
+            // --- threads, messages, telemetry -------------------------------
+            await client.query('UPDATE wa_conversations SET user_id = $1 WHERE user_id = $2', [keepId, dropId]);
+            await client.query('UPDATE wa_messages SET user_id = $1 WHERE user_id = $2', [keepId, dropId]);
+            await client.query('UPDATE wa_ai_usage SET user_id = $1 WHERE user_id = $2', [keepId, dropId]);
+
+            // --- aliases -----------------------------------------------------
+            await client.query(
+                'UPDATE wa_user_identities SET user_id = $1, is_primary = FALSE WHERE user_id = $2',
+                [keepId, dropId]
+            );
+
+            // --- roll the counters and the best-known profile up ------------
+            await client.query(
+                `UPDATE wa_users k SET
+                     message_count  = k.message_count + d.message_count,
+                     token_estimate = k.token_estimate + d.token_estimate,
+                     push_name      = COALESCE(k.push_name, d.push_name),
+                     display_name   = COALESCE(k.display_name, d.display_name),
+                     phone          = COALESCE(k.phone, d.phone),
+                     locale         = COALESCE(k.locale, d.locale),
+                     is_blocked     = k.is_blocked OR d.is_blocked,
+                     is_admin       = k.is_admin OR d.is_admin,
+                     metadata       = d.metadata || k.metadata,
+                     last_seen_at   = GREATEST(k.last_seen_at, d.last_seen_at),
+                     updated_at     = NOW()
+                  FROM wa_users d
+                 WHERE k.id = $1 AND d.id = $2`,
+                [keepId, dropId]
+            );
+
+            await client.query('DELETE FROM wa_users WHERE id = $1', [dropId]);
+            await client.query('UPDATE wa_user_identities SET is_primary = TRUE WHERE user_id = $1 AND jid = (SELECT jid FROM wa_users WHERE id = $1)', [keepId]);
+
+            const { rows: kept } = await client.query('SELECT * FROM wa_users WHERE id = $1', [keepId]);
+            return kept[0];
+        });
+    }
+
+    /** Make `rawJid` the canonical address of a user (used for context keys). */
+    async setPrimary(userId, rawJid) {
+        const jid = JidParser.normalize(rawJid);
+        if (!userId || !jid) return null;
+        await this.db.query('UPDATE wa_user_identities SET is_primary = (jid = $2) WHERE user_id = $1', [
+            userId,
+            jid,
+        ]);
+        return this.db.one('UPDATE wa_users SET jid = $2 WHERE id = $1 RETURNING *', [userId, jid]).catch(() => null);
+    }
+
+    /** The stable jid used to build conversation keys for this user. */
+    async primaryJid(userId, fallback = null) {
+        if (!userId) return fallback;
+        const row = await this.db.one(
+            `SELECT jid FROM wa_user_identities
+              WHERE user_id = $1
+              ORDER BY is_primary DESC, first_seen_at ASC
+              LIMIT 1`,
+            [userId]
+        );
+        return row?.jid || fallback;
+    }
+}
+
+module.exports = IdentityRepository;