@manybot/manybot 5.8.0 → 5.9.1

package/README.md

@@ -1,6 +1,3 @@
-> [!WARNING]
-> Versions 5.6.x and 5.7.x are UNSTABLE because of management error. Please use 5.5.4 instead. 
-
 <div align="center">
 
 ![ManyBot Logo](logo.png)
@@ -66,12 +63,23 @@ npm test
 # Run all verification gates (typecheck + lint + unit tests)
 npm run check
 
-# Run real WhatsApp integration tests (requires TEST_CHAT and live session)
-TEST_CHAT="5516999999999" npm run test:integration
+# Run real WhatsApp integration tests against a live account.
+# Requires: TEST_CHAT, MANYBOT_RUN_WHATSAPP_TESTS=1, and a saved
+# WhatsApp session in your CONFIG_DIR. The bare variant below
+# always skips every test (no live socket). Use `:local` to boot
+# the bot first — it preloads src/main.ts so the driver connects
+# before the test runner kicks in.
+TEST_CHAT="5516999999999" MANYBOT_RUN_WHATSAPP_TESTS=1 npm run test:integration:local
+
+# Manual smoke probe: connects, runs a few marker round-trips, and
+# prints the IContact shape (id / number / numberRaw / numberPretty /
+# country / countryCallingCode) returned by contacts.get(...) — useful
+# for verifying the LID-aware contact API against your real account
+# without the full test runner overhead.
+TEST_CHAT="5516999999999" MANYBOT_RUN_WHATSAPP_TESTS=1 \
+  node --import ./src/main.ts scripts/probe-contacts.mjs
 ```
 
-For full details on the test architecture and API coverage classification, see [API_TEST_PLAN.md](API_TEST_PLAN.md).
-
 ## Contributing
 
 All kinds of contributions are welcome:

package/dist/client/store.js

@@ -18,6 +18,7 @@
  * @whiskeysockets/baileys import line never leaks past the driver
  * boundary.
  */
+import { normalizeJid } from "#drivers/jid.js";
 // ── Factory ───────────────────────────────────────────────────────────────────
 /**
  * Create a new BotStore instance.
@@ -30,9 +31,23 @@ export function createStore() {
     // @lid JID → traditional @s.whatsapp.net JID, learned from contact and
     // message-key pairs (Baileys exposes both forms during the LID rollout).
     const lidMap = new Map();
+    // traditional @s.whatsapp.net JID → @lid JID, reverse mapping for lookups.
+    const pnMap = new Map();
     function learnLid(lid, pn) {
-        if (lid && pn && lid.endsWith("@lid") && !pn.endsWith("@lid"))
+        if (lid && pn && lid.endsWith("@lid") && !pn.endsWith("@lid")) {
+            // lidMap keeps the wire-format value as given — resolveJid()
+            // consumers (e.g. adapter.ts building self/participant candidates
+            // via jidNormalizedUser) expect the raw "@s.whatsapp.net" shape.
             lidMap.set(lid, pn);
+            // pnMap's key is canonicalized to ManyBot's internal "@c.us" form
+            // so a lookup matches regardless of which format the caller has on
+            // hand — callers deep in the driver (adapter.ts) query it with raw
+            // wire JIDs, while callers in the plugin-facing API (index.ts) query
+            // it with already-normalized JIDs. Without this, pn entries learned
+            // in one format silently never matched a resolvePn() call made in
+            // the other.
+            pnMap.set(normalizeJid(pn), lid);
+        }
     }
     function resolveJid(jid) {
         if (!jid || !jid.endsWith("@lid"))
@@ -40,8 +55,16 @@ export function createStore() {
         return lidMap.get(jid) ?? jid;
     }
     function forgetLid(lid) {
+        const pn = lidMap.get(lid);
+        if (pn)
+            pnMap.delete(normalizeJid(pn));
         lidMap.delete(lid);
     }
+    function resolvePn(pn) {
+        if (!pn)
+            return null;
+        return pnMap.get(normalizeJid(pn)) ?? null;
+    }
     // Coerce the various shapes Baileys delivers `ephemeralExpiration` in
     // (string-numbered from the wire, `null` when the timer was cleared,
     // or absent entirely) into a plain finite number. Anything we can't
@@ -223,6 +246,7 @@ export function createStore() {
             chats: [...chatsMap.values()],
             contacts: { ...contacts },
             lidMap: [...lidMap.entries()],
+            pnMap: [...pnMap.entries()],
         };
     }
     function hydrate(snapshot) {
@@ -231,6 +255,15 @@ export function createStore() {
         for (const [id, contact] of Object.entries(snapshot.contacts ?? {})) {
             contacts[id] = { ...contacts[id], ...contact };
         }
+        // learnLid() always mirrors into both lidMap and pnMap, so replaying
+        // snapshot.lidMap alone fully reconstructs pnMap too — every pnMap
+        // entry has a corresponding lidMap entry, they're never written
+        // independently. snapshot.pnMap itself is redundant to replay here:
+        // it exists only so `toJSON()`'s output is self-describing/inspectable,
+        // and re-learning from it a second time would re-derive pnMap's key
+        // (already-canonicalized "@c.us" form) as if it were lidMap's raw
+        // wire-format value, corrupting the wire-format invariant lidMap's
+        // consumers (e.g. adapter.ts) depend on.
         for (const [lid, pn] of snapshot.lidMap ?? [])
             learnLid(lid, pn);
     }
@@ -244,6 +277,7 @@ export function createStore() {
         resolveJid,
         learnLid,
         forgetLid,
+        resolvePn,
         setChatEphemeralExpiration,
         bind,
         toJSON,

package/dist/download/queue.js

@@ -10,6 +10,9 @@
  * Usage:
  *   import { enqueue } from "#download";
  *   enqueue(async () => { ... all plugin logic ... }, onError);
+ *
+ * `errorFn` is optional — if omitted, a failure is still logged via
+ * `logger.warn` so it's never silently swallowed.
  */
 import { logger } from "#logger";
 import { t } from "#i18n";
@@ -18,7 +21,8 @@ let processing = false;
 /**
  * Add a job to the queue and start processing if idle.
  * @param workFn  All plugin logic — runs exclusively until resolved.
- * @param errorFn Called with the thrown error if workFn rejects.
+ * @param errorFn Called with the thrown error if workFn rejects. If omitted,
+ *                 the error is logged via `logger.warn` instead.
  */
 export function enqueue(workFn, errorFn) {
     queue.push({ workFn, errorFn });
@@ -41,9 +45,14 @@ async function processJob({ workFn, errorFn }) {
     catch (e) {
         const err = e instanceof Error ? e : new Error(String(e));
         logger.error(t("system.downloadJobFailed", { message: err.message }));
-        try {
-            await errorFn(err instanceof Error ? err : new Error(String(err)));
+        if (errorFn) {
+            try {
+                await errorFn(err);
+            }
+            catch { }
+        }
+        else {
+            logger.warn(t("system.downloadJobNoErrorFn"));
         }
-        catch { }
     }
 }

package/dist/drivers/baileys/adapter.js

@@ -25,6 +25,7 @@
 import { normalizeMessageContent, downloadMediaMessage, jidNormalizedUser, decryptPollVote as baileysDecryptPollVote, getAggregateVotesInPollMessage, } from "@whiskeysockets/baileys";
 import { createHash } from "node:crypto";
 import { logger } from "#logger";
+import { splitLidPn } from "#drivers/jid.js";
 /**
  * Classify a Baileys message-content payload (`WAMessageContent`) into
  * the neutral `(type, body, mimetype)` triple used by `BotMessage`. Pure
@@ -180,7 +181,17 @@ export function createBaileysAdapter(initial) {
         }
         return hash.digest("hex");
     }
-    /** Translate a Baileys WAMessage into the neutral BotMessage envelope. */
+    /** Normalize a mentioned JID: convert PN JIDs to LID when a mapping is known. */
+    function normalizeMentionedJid(jid) {
+        if (!jid)
+            return jid;
+        // Already LID — pass through.
+        if (jid.endsWith("@lid"))
+            return jid;
+        // Phone-based JID: look up the LID in the reverse map.
+        const lid = store.resolvePn(jid);
+        return lid ?? jid;
+    }
     function toBotMessage(msg) {
         const m = normalizeMessageContent(msg.message) ?? undefined;
         const { type, body, mimetype } = decodeContent(msg.message);
@@ -195,6 +206,11 @@ export function createBaileysAdapter(initial) {
             m?.buttonsMessage?.contextInfo ??
             undefined;
         const ciTyped = contextInfo;
+        // See splitLidPn() — `key.participant`/`key.remoteJid` are only the PN
+        // form under legacy `addressingMode: "pn"`; under the modern default
+        // "lid" mode they're already the LID and the *Alt field carries the PN.
+        const participantIds = splitLidPn(key.participant, key.participantAlt);
+        const remoteJidIds = splitLidPn(key.remoteJid, key.remoteJidAlt);
         return {
             id: msg.key.id ?? "",
             chatId: msg.key.remoteJid ?? "",
@@ -205,17 +221,23 @@ export function createBaileysAdapter(initial) {
             body,
             mimetype: mimetype ?? undefined,
             pushName: msg.pushName,
-            mentionedJid: ciTyped?.mentionedJid ?? undefined,
+            mentionedJid: ciTyped?.mentionedJid?.map(normalizeMentionedJid) ?? undefined,
             quotedKey: ciTyped?.stanzaId ? {
                 id: ciTyped.stanzaId,
                 remoteJid: msg.key.remoteJid ?? undefined,
                 fromMe: false,
                 participant: ciTyped.participant ?? undefined,
             } : undefined,
-            fromLid: key.participantAlt,
-            fromPn: key.participant,
-            participantAlt: key.participantAlt,
-            remoteJidAlt: key.remoteJidAlt,
+            // Resolve LID/PN by actual JID suffix, not by field position — see
+            // splitLidPn() for why `key.participantAlt` can't be trusted to
+            // always be the LID. `participantAlt`/`remoteJidAlt` below are
+            // reassigned to the suffix-verified LID (or `undefined` if neither
+            // candidate is one), so every existing consumer that reads them
+            // directly gets the corrected value for free.
+            fromLid: participantIds.lid,
+            fromPn: participantIds.pn,
+            participantAlt: participantIds.lid,
+            remoteJidAlt: remoteJidIds.lid,
             // Driver-specific escape hatches:
             //   - pollEncKeyRaw: poll-decryption key for vote decryption
             //   - contextInfo:   full IContextInfo (incl. embedded quotedMessage)
@@ -478,6 +500,16 @@ export function createBaileysAdapter(initial) {
             if (rawDuration !== undefined) {
                 store.setChatEphemeralExpiration(jid, Number(rawDuration) || 0);
             }
+            // Baileys v7's GroupMetadata carries per-participant `id` (LID, the
+            // addressing mode the group uses) AND `phoneNumber` (the traditional
+            // PN form). Feed the LID↔PN store for any participant that carries
+            // both — passive cache, never a network call.
+            for (const p of meta.participants) {
+                const lid = p.id;
+                const phone = p.phoneNumber;
+                if (lid && phone)
+                    store.learnLid(lid, phone);
+            }
             return {
                 subject: meta.subject,
                 participants: meta.participants.map(p => ({
@@ -727,8 +759,37 @@ export function createBaileysAdapter(initial) {
             emit("contacts.update", { updates: arg.map(contactSummary) });
         });
         register("group-participants.update", (arg) => {
-            const { id, participants } = arg;
-            emit("group-participants.update", { id, participants });
+            // Baileys v7 ships `participants` as GroupParticipant[] (Contact & { admin… }),
+            // carrying `id`, `lid?`, and `phoneNumber?` per entry. The kernel-public
+            // contract still uses `string[]` of JIDs (one per participant), so we
+            // project `id` down here — but we also take the opportunity to feed the
+            // LID↔PN store from the richer data while we have it: when a single
+            // payload delivers both forms of the same identity, that's the cleanest
+            // mapping we can ever hope to learn.
+            const a = arg;
+            const jids = a.participants.map(p => jidNormalizedUser(p.id));
+            for (const p of a.participants) {
+                // v7 sometimes provides both forms; sometimes only one. Use whichever
+                // is available — learnLid() filters out incomplete or non-LID inputs.
+                // The richest case is `lid` + `phoneNumber` both explicit; otherwise
+                // we accept `lid`+`id` or `id`+`phoneNumber` (Baileys commonly puts
+                // the LID in `id` and the PN in `phoneNumber` on group metadata).
+                if (p.lid && p.phoneNumber)
+                    store.learnLid(p.lid, p.phoneNumber);
+                else if (p.lid && p.id)
+                    store.learnLid(p.lid, p.id);
+                else if (p.id && p.phoneNumber)
+                    store.learnLid(p.id, p.phoneNumber);
+            }
+            // authorPn (the inviter's PN) is the same source of truth — feed it too.
+            if (a.author && a.authorPn)
+                store.learnLid(a.author, a.authorPn);
+            emit("group-participants.update", {
+                id: a.id,
+                author: a.author,
+                participants: jids,
+                action: a.action,
+            });
         });
         register("groups.upsert", (arg) => {
             const groups = arg;
@@ -738,7 +799,13 @@ export function createBaileysAdapter(initial) {
             emit("groups.update", { updates: arg });
         });
         register("group.join-request", (arg) => {
+            // Baileys v7 emits `participantPn` (and `authorPn`) on the join-request
+            // payload — feed the LID↔PN store from those while we have both sides.
             const a = arg;
+            if (a.participant && a.participantPn)
+                store.learnLid(a.participant, a.participantPn);
+            if (a.author && a.authorPn)
+                store.learnLid(a.author, a.authorPn);
             emit("group.join-request", {
                 id: a.id,
                 author: a.author,

package/dist/drivers/baileys/api/contacts.integration.test.js

@@ -0,0 +1,261 @@
+/**
+ * src/drivers/baileys/api/contacts.integration.test.ts
+ *
+ * Real-WhatsApp integration tests for the LID-aware contact API surface
+ * (`IContact.id` is LID-or-null, `number`/`numberRaw`/`numberPretty`/
+ * `country`/`countryCallingCode` populated by libphonenumber-js).
+ *
+ * Exercises the full driver stack end-to-end:
+ *   - The integration plugin (gated by `MANYBOT_RUN_WHATSAPP_TESTS=1`)
+ *     drives real sends + listens for the test marker's echo.
+ *   - Each test sends a uniquely-prefixed message into the configured
+ *     `TEST_CHAT`, waits for the round-trip, then reads
+ *     `ctx.contacts.get(...)` from a freshly-built plugin context and
+ *     asserts the new shape is honored against a live WhatsApp account.
+ *
+ * All tests skip when integration mode is not fully ready (no opt-in,
+ * no `TEST_CHAT`, or no saved WhatsApp session). Skipped tests do not
+ * count as failures — they're informational.
+ *
+ * Requires:
+ *   - `MANYBOT_RUN_WHATSAPP_TESTS=1`
+ *   - `TEST_CHAT="<phone>"` (env or manybot.toml) — MUST be an
+ *     individual chat (a bare phone number, or a JID ending in
+ *     `@s.whatsapp.net`/`@c.us`/`@lid`), NOT a group (`@g.us`).
+ *     Every assertion below reads per-person contact fields (LID,
+ *     E.164 number, numberPretty, country, countryCallingCode) —
+ *     `normalizeContact()` (src/drivers/baileys/api/index.ts) never
+ *     populates any of those for a group JID, since a group has no
+ *     LID or phone number of its own. Sending/receiving still works
+ *     fine against a group (the round-trip itself doesn't care), so
+ *     a group `TEST_CHAT` will pass the integration-mode gate and
+ *     even echo markers successfully, then fail every shape
+ *     assertion below with `expected: /@lid$/, actual: "...@g.us"`
+ *     (and `null` for number/country/etc.) — if you see that
+ *     specific failure pattern, point TEST_CHAT at a DM instead.
+ *   - A logged-in WhatsApp session (creds.json + app-state-sync-… in
+ *     CONFIG_DIR, same as a normal run).
+ *   - Either:
+ *       - `npm run test:integration:local`  — boots `src/main.ts` first
+ *         so the bot connects and the integration plugin is registered;
+ *       - a one-shot manual run with the integration plugin loaded by
+ *         the caller (see scripts/probe-contacts.mjs).
+ *
+ * `npm run test:integration` (without `:local`) is supported but every
+ * test will skip because no live socket exists in that mode.
+ */
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import { loadIntegrationPlugin, pluginRegistry, getGlobalKernelRefs, } from "#kernel/pluginLoader.js";
+import { getIntegrationModeStatus, INTEGRATION_PLUGIN_NAME } from "#kernel/integrationMode.js";
+import { logger } from "#logger";
+// ── Integration-mode gate (resolved at top level) ────────────────────────────
+//
+// Two distinct gates need to pass before a test runs:
+//
+//   1. Configuration gate (`getIntegrationModeStatus().ready`):
+//      MANYBOT_RUN_WHATSAPP_TESTS=1 is set AND TEST_CHAT is configured
+//      (env or manybot.toml). This is what `npm run test:integration`
+//      auto-enables via the script's env prefix.
+//
+//   2. Live-socket gate (`getGlobalKernelRefs() !== null`):
+//      The Baileys driver has actually connected at least once so a
+//      `WaContract` is available for real sends. With
+//      `npm run test:integration:local` (which boots main.ts first),
+//      this resolves as soon as the bot connects. With the bare
+//      `npm run test:integration` (no main.ts preload), it never
+//      resolves and every test skips — which is correct.
+//
+// We resolve both gates up-front (top-level await) instead of in a
+// `before()` hook so the `{ skip: !integrationReady }` option on
+// each `test()` call is honored by the runner — an early-return
+// inside the test body looks like `pass: N` in CI output, which is
+// confusing when scanning for "did this actually run?".
+let integrationReady = false;
+let integrationSkipReason = "not evaluated";
+let integrationChat = null;
+let kernelRefs = null;
+async function evaluateGates() {
+    const status = await getIntegrationModeStatus();
+    const configReady = status.ready;
+    const configReason = status.reason ?? "";
+    integrationChat = status.chat;
+    // Make sure the integration plugin is registered — its `setup()`
+    // populates `api.testChat` and `api.waitForMarker`, both needed by
+    // the test helpers below. When the bot is already running (the
+    // `:local` variant), `loadPlugins`/`setupPlugins` ran during boot
+    // and called `loadIntegrationPlugin()` for us; `loadIntegrationPlugin`
+    // is idempotent so calling it again here is safe.
+    if (configReady) {
+        try {
+            await loadIntegrationPlugin();
+        }
+        catch (e) {
+            logger.warn(`[contacts.integration] loadIntegrationPlugin failed: ${e.message}`);
+        }
+    }
+    // With `npm run test:integration:local`, main.ts is preloaded and
+    // begins connecting as soon as it's imported — the test runner may
+    // execute this file before the connection has resolved. Poll for
+    // the global refs for up to 60s before giving up; this lets
+    // contributors run the suite immediately after `node main.ts` and
+    // have it work without manual timing.
+    const SOCKET_WAIT_MS = 60_000;
+    const deadline = Date.now() + SOCKET_WAIT_MS;
+    while (Date.now() < deadline) {
+        kernelRefs = getGlobalKernelRefs();
+        if (kernelRefs)
+            break;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    const socketReady = kernelRefs !== null;
+    integrationReady = configReady && socketReady;
+    integrationSkipReason = !configReady
+        ? configReason
+        : `bot did not connect within ${SOCKET_WAIT_MS / 1000}s — check the main.ts preload output for connection errors`;
+    if (integrationReady) {
+        logger.info(`[contacts.integration] integration mode ready — chat=${integrationChat} ` +
+            `kernelRefs=${!!kernelRefs}`);
+    }
+    else {
+        logger.warn(`[contacts.integration] integration mode NOT ready — ${integrationSkipReason}. ` +
+            `Every test in this file will skip.`);
+    }
+}
+// Resolve the gates up-front. Top-level await pauses module
+// initialization until `evaluateGates()` resolves, so by the time any
+// `test()` call below is reached the `integrationReady` flag is
+// stable. This is what lets us pass `{ skip: !integrationReady }` to
+// each test — `node:test` honors the flag at test-definition time.
+await evaluateGates();
+function getIntegrationApi() {
+    const entry = pluginRegistry.get(INTEGRATION_PLUGIN_NAME);
+    if (!entry || entry.status !== "active")
+        return null;
+    return entry.exports;
+}
+const ROUND_TRIP_TIMEOUT_MS = 30_000;
+/**
+ * Send a marker-prefixed message into the test chat and wait for an
+ * inbound message with the same marker — exercises the round-trip
+ * (BotStore + adapter + listener + contact store feeding) that the
+ * LID/PN resolution depends on.
+ */
+async function sendAndAwaitEcho(api, contract, marker, opts) {
+    await contract.sendText(api.testChat, marker, opts);
+    await api.waitForMarker(marker, ROUND_TRIP_TIMEOUT_MS);
+}
+// ── Tests ────────────────────────────────────────────────────────────────────
+//
+// All tests below pass `{ skip: !integrationReady }` so they report
+// as `skipped` in CI output (not `pass`) when the integration suite
+// can't actually run. The `if (!integrationReady) return;` guard at
+// the top of each test body is belt-and-braces — if the skip flag is
+// ever ignored (e.g. someone wires this suite into a different
+// runner), the test still no-ops instead of crashing on a null
+// `integrationChat`.
+describe("contacts.integration — gate", () => {
+    test("integration mode reports ready (sanity)", { skip: !integrationReady }, () => {
+        assert.ok(integrationSkipReason, "skip reason must explain the skip");
+        assert.equal(integrationReady, true, "integration mode must be ready for this suite to run");
+        assert.ok(integrationChat, "integration chat must be configured when ready");
+        assert.ok(kernelRefs, "live WaContract must be available when integration mode is ready");
+    });
+});
+describe("contacts.integration — IContact shape on a live WhatsApp account", () => {
+    test("id is the LID form (preferred canonical identifier)", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs, "integration api + kernel refs must be available");
+        const marker = `ICONTACT-ID-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.ok(me, "expected contacts.get to resolve the test chat");
+        assert.match(me.id ?? "", /@lid$/, `expected id to be @lid form, got ${me.id}`);
+    });
+    test("number is canonical E.164 with leading +", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-NUMBER-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.number ?? "", /^\+\d+$/, `expected E.164 with +, got ${me.number}`);
+    });
+    test("numberPretty is internationally formatted", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-PRETTY-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.ok((me.numberPretty ?? "").startsWith("+"), `expected pretty form to start with +, got ${me.numberPretty}`);
+    });
+    test("country is ISO alpha-2", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-COUNTRY-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.country ?? "", /^[A-Z]{2}$/, `expected ISO alpha-2, got ${me.country}`);
+    });
+    test("countryCallingCode is the ITU dial code", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `ICONTACT-CC-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.countryCallingCode ?? "", /^\d{1,4}$/, `expected ITU dial code, got ${me.countryCallingCode}`);
+    });
+});
+describe("contacts.integration — LID↔PN cache populated by a real round-trip", () => {
+    test("after one round-trip the @s.whatsapp.net form resolves back to LID", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `PNMAP-CACHE-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const lid = kernelRefs.store.resolvePn(api.testChat);
+        assert.ok(lid, `expected pnMap to have learned the LID for ${api.testChat}`);
+        assert.match(lid, /@lid$/, `expected resolved LID, got ${lid}`);
+    });
+    test("contacts.get(normalizedPn) returns LID-backed IContact after cache warmup", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `GET-PN-RESOLVES-LID-${Date.now()}-`;
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker);
+        const me = await (await import("#drivers/baileys/api/index.js")).buildContactsApi(kernelRefs.contract, kernelRefs.store, null).get(api.testChat);
+        assert.match(me.id ?? "", /@lid$/, "expected LID form after cache warmup");
+    });
+});
+describe("contacts.integration — mentionedJid is normalized to LID form", () => {
+    test("sending a real mention succeeds and the store learns a LID↔PN pair", { skip: !integrationReady }, async () => {
+        const api = getIntegrationApi();
+        assert.ok(api && kernelRefs);
+        const marker = `MENTION-LID-${Date.now()}-`;
+        // WaContract.sendText() already accepts `mentions` — no need to reach
+        // into Baileys internals to send a real mention (see waContract.ts).
+        // Modern WhatsApp delivers contextInfo.mentionedJid in @lid form
+        // already (confirmed against WhiskeySockets/Baileys#1683/#1667), so
+        // there's no PN→LID "resolution" for a mention to teach — this test
+        // just proves the send round-trips and, if the account has a phone
+        // number mapping learned along the way (e.g. via the contact/message
+        // sync that accompanies any real WhatsApp exchange), the store
+        // reflects it.
+        await sendAndAwaitEcho(api, kernelRefs.contract, marker, { mentions: [api.testChat] });
+        const bodies = api.recentBodies();
+        assert.ok(bodies.some((b) => b.startsWith(marker)), `expected recent bodies to include "${marker}" — got ${JSON.stringify(bodies)}`);
+        const lidKeys = Object.keys(kernelRefs.store.contacts).filter((k) => k.endsWith("@lid"));
+        assert.ok(lidKeys.length > 0, `expected store.contacts to contain at least one @lid key after mention round-trip — got ${JSON.stringify(Object.keys(kernelRefs.store.contacts))}`);
+    });
+});
+// ── Live-harness readiness probe ────────────────────────────────────────────
+//
+// Single test that fails (rather than skips) when the harness is
+// missing a piece — useful so a contributor who has TEST_CHAT + a
+// session can immediately see what's still left to wire. Skips
+// cleanly when integration mode isn't ready at all.
+describe("contacts.integration — harness readiness", () => {
+    test("integration plugin is registered and active", { skip: !integrationReady }, () => {
+        const entry = pluginRegistry.get(INTEGRATION_PLUGIN_NAME);
+        assert.ok(entry, `expected "${INTEGRATION_PLUGIN_NAME}" to be registered in pluginRegistry`);
+        assert.equal(entry.status, "active", `expected plugin status "active", got "${entry.status}"`);
+        assert.ok(entry.exports, "expected integration plugin exports to be populated");
+    });
+});