@xuda.io/account_module 1.2.2309 → 1.2.2311

package/index.mjs

@@ -3535,6 +3535,7 @@ export const get_account_name = async function (req) {
       active_account_profile_id,
       network_country_code,
       public_profile_disabled,
+      verify_level,
     } = data.data.account_info;
 
     obj = {
@@ -3570,6 +3571,11 @@ export const get_account_name = async function (req) {
       // email,// email?.[0] || '',
       avatar_source,
       active_account_profile_id,
+      // The verification level of the account behind a card. Every caller that
+      // builds a contact card off another account copies this onto the card doc
+      // so the background tile can say what the level is; without it a card for
+      // a verified person read as L0, which is a false statement about them.
+      verify_level,
     };
   }
   return { code: 1, data: obj }; //is_online: data?.data?.socket_id ? true : false
@@ -4247,6 +4253,7 @@ export const merge_contact = async function (req) {
   }
 
   const primary_contact_save_ret = await save_contact(uid, primary_contact_doc);
+  log_contact_activity(uid, contact_to_merge, 'merged_in', { count: contact_to_delete.length, emails: primary_contact_doc.email, note: 'kept as the primary of a duplicate set' });
 
   for (let contact_id of contact_to_delete) {
     try {
@@ -4255,6 +4262,7 @@ export const merge_contact = async function (req) {
       contact_doc.stat_ts = Date.now();
       contact_doc.stat_reason = 'merge';
       await save_contact(uid, contact_doc);
+      log_contact_activity(uid, contact_id, 'merged_away', { into: contact_to_merge, note: 'folded into the primary duplicate and closed' });
     } catch (error) {}
   }
 
@@ -4303,6 +4311,13 @@ const level_pattern = function (doc) {
   return `level-${level}-pattern.png`;
 };
 
+// The level tile is the DEFAULT for every contact card, not a fallback. It used
+// to be computed first and then overwritten by a tile keyed off where the
+// contact came from (xu / authentic / fictional / email / web), so a card for a
+// verified person showed the generic XU tile and the level never appeared on any
+// card that had a contact_uid, which is every card for a real account. Only the
+// states that say the card cannot show a level at all still win: a shared card
+// wears its owner's avatar, an avatar being processed says so, and spam says so.
 const get_contact_pattern = async function (doc) {
   let ret = level_pattern(doc);
 
@@ -4323,84 +4338,12 @@ const get_contact_pattern = async function (doc) {
     }
   } else if (doc.is_spam) {
     ret = `spam-pattern.png`;
-  } else {
-    // if (doc.account_type === 'business') {
-    //   // if (doc?.is_real_person) {
-    //   ret = doc.profile_picture;
-    //   // }
-    // } else {
-    // if (doc.my_contact) {
-    //   if (doc.account_type === 'business') {
-    //     ret = doc.profile_picture;
-    //   } else {
-    //     switch (doc.avatar_source) {
-    //       case 'fictional':
-    //         ret = `fictional-avatar-pattern.png`;
-    //         break;
-
-    //       case 'ai profile':
-    //         ret = `fictional-avatar-pattern.png`;
-    //         break;
-
-    //       case 'authentic profile':
-    //         ret = `authentic-avatar-pattern.png`;
-    //         break;
-
-    //       default:
-    //         ret = `xu-pattern.png`;
-    //         break;
-    //     }
-    //   }
-    // } else
-
-    // if (doc?.shared_from_uid) {
-    //   //&& (doc.pending || (doc.team_req_id && doc.contact_share_copy))) {
-    //   // pending or active share request
-    //   const shared_from_uid_ret = await get_account_name({ uid_query: doc.shared_from_uid });
-    //   ret = shared_from_uid_ret.data.profile_avatar;
-    // }
-
-    // else if (doc?.reference_doc?.shared_from_uid) {
-    //   //active share
-    //   const shared_from_uid_ret = await get_account_name({ uid_query: doc.reference_doc.shared_from_uid });
-    //   ret = shared_from_uid_ret.data.profile_avatar;
-    // }
-    // else
-    if (doc.contact_uid) {
-      switch (doc.avatar_source) {
-        case 'fictional':
-          ret = `fictional-avatar-pattern.png`;
-          break;
-
-        case 'ai profile':
-          ret = `fictional-avatar-pattern.png`;
-          break;
-
-        case 'authentic profile':
-          ret = `authentic-avatar-pattern.png`;
-          break;
-
-        default:
-          ret = `xu-pattern.png`;
-          break;
-      }
-    } else {
-      switch (doc.source) {
-        case 'read emails': {
-          ret = `email-pattern.png`;
-          break;
-        }
-        case 'web': {
-          ret = `web-pattern.png`;
-          break;
-        }
-
-        default:
-          break;
-      }
-    }
-    // }
   }
+  // Everything else keeps the level tile. The old where-it-came-from tiles
+  // (xu / authentic / fictional for an account, email / web for a scraped
+  // contact) are gone on purpose: they occupied the one surface that now
+  // carries the verification level, and a contact with no account behind it
+  // has no level to show, which is exactly what L0 says.
   return ret;
 };
 
@@ -4568,6 +4511,10 @@ export const get_contact_info = async function (uid, contact_doc, _id) {
       }
 
       doc.avatar_source = account_info_ret.data.avatar_source;
+      // The card's background tile is the contact's verification level, and the
+      // level lives on the account, not on my copy of them. Carry it over here,
+      // where the account is already in hand, so the tile costs no extra read.
+      doc.verify_level = account_info_ret.data.verify_level;
       // doc.icon_pattern = await get_contact_pattern(doc);
       doc.username = account_info_ret.data.username;
       doc.business_name = account_info_ret.data.business_name;
@@ -4632,6 +4579,7 @@ export const get_pending_contact_out = async function (uid, _id) {
       doc.account_type = account_info_ret.data.account_type;
       doc.avatar_source = account_info_ret.data.avatar_source;
       doc.profile_avatar = account_info_ret.data.profile_avatar;
+      doc.verify_level = account_info_ret.data.verify_level;
       doc.name = `${account_info_ret.data.first_name} ${account_info_ret.data.last_name}`;
     }
     doc.icon_pattern = await get_contact_pattern(doc);
@@ -4663,6 +4611,7 @@ export const get_pending_contact_in = async function (uid, _id) {
       doc.account_type = account_info_ret.data.account_type;
       doc.avatar_source = account_info_ret.data.avatar_source;
       doc.profile_avatar = account_info_ret.data.profile_avatar;
+      doc.verify_level = account_info_ret.data.verify_level;
       doc.name = `${account_info_ret.data.first_name} ${account_info_ret.data.last_name}`;
     }
     doc.card_background = get_contact_background({ pending: true });
@@ -4702,6 +4651,7 @@ const get_user_contact = async function (uid, uid_query) {
   doc.profile_avatar = account_info.profile_avatar;
   doc.profile_picture = account_info.profile_picture;
   doc.avatar_source = account_info.avatar_source;
+  doc.verify_level = account_info.verify_level;
   doc.card_background = get_contact_background(doc);
   doc.icon_pattern = await get_contact_pattern(doc);
   doc.border = get_contact_border(doc);
@@ -4753,7 +4703,9 @@ export const update_contact = async function (req) {
       doc.profile_avatar = account_obj.account_info.profile_avatar;
     }
 
-    return await save_contact(uid, doc);
+    const save_ret = await save_contact(uid, doc);
+    log_contact_activity(uid, doc._id, 'updated', { stat, team_req_id, linked_account: contact_uid, note: contact_uid ? 'picture and avatar taken from the linked Xuda account' : undefined });
+    return save_ret;
   }
   return { code: -1, data: 'contact not found' };
 };
@@ -5614,28 +5566,18 @@ setTimeout(async () => {
 
 //////// CONTACTS  //////////////
 
-function identifyPersonalProvider(domain) {
-  const providers = {
-    'gmail.com': 'Google Gmail',
-    'googlemail.com': 'Google Gmail',
-    'outlook.com': 'Microsoft Outlook',
-    'hotmail.com': 'Microsoft Hotmail',
-    'live.com': 'Microsoft Live',
-    'yahoo.com': 'Yahoo Mail',
-    'ymail.com': 'Yahoo Mail',
-    'aol.com': 'AOL Mail',
-    'icloud.com': 'Apple iCloud',
-    'me.com': 'Apple iCloud',
-    'mac.com': 'Apple iCloud',
-    'protonmail.com': 'ProtonMail',
-    'proton.me': 'ProtonMail',
-    'zoho.com': 'Zoho Mail',
-    'yandex.com': 'Yandex Mail',
-    'mail.com': 'Mail.com',
-    'gmx.com': 'GMX Mail',
-  };
+// A "business" that resolves to the address's own mail provider is not the contact's
+// employer, it is Gmail. get_business_info, handed a bare gmail.com address, answers
+// "Gmail / gmail.com / Technology" rather than "Not available", so the only escape hatch the
+// classification had (business_name === 'Not available') never fired and every personal
+// Gmail contact came out as a business, storefront placeholder and all. This is the second
+// escape hatch, built on the provider list that already exists directly below.
+const businessIsJustTheMailProvider = (business_info) => !!identifyPersonalProvider(business_info?.business_domain || '');
 
-  return providers[domain.toLowerCase()];
+function identifyPersonalProvider(domain) {
+  // The list moved to common so ai_module's contact classifier reads the same one. It used to
+  // live here alone, which is exactly why the classifier could call gmail.com a business.
+  return _common.personal_email_provider(domain);
 }
 
 export const add_contact = async function (req, job_id, headers) {
@@ -5663,6 +5605,16 @@ export const add_contact = async function (req, job_id, headers) {
 
     /////////////////
 
+    // Minted up front rather than at save time, so every classification step
+    // below can file its verdict under the contact it is deciding about. The
+    // steps run BEFORE the doc exists, which is exactly why their reasoning
+    // used to be unrecoverable.
+    const contact_id = await _common.xuda_get_uuid('contact');
+    const app_id = account_profile_info.app_id;
+    const activity = (event, detail) => log_contact_activity(uid, contact_id, event, detail, app_id);
+
+    await activity('created', { source: source || 'unknown', email: email.toLowerCase(), name: name || '', from_account: !!contact_uid, subject: metadata.subject, profile_id: account_profile_obj?._id });
+
     let is_spam = false;
     // let email_type_info;
     // let account_type_info;
@@ -5679,27 +5631,45 @@ export const add_contact = async function (req, job_id, headers) {
       }
 
       set_account_profile_picture(uid, contact_uid, metadata, job_id, headers, account_profile_info);
+      await activity('linked_account', { contact_uid });
     } else {
       is_spam = await isLikelySpamEmail(email);
+      if (is_spam) await activity('spam_check', { by: 'pattern', is_spam: true, note: 'address matched the local spam pattern list, no AI step ran' });
 
       // contact without use account
       cached_contact = await get_xuda_cache(uid, 'contact', email, 'metadata');
+      if (!_.isEmpty(cached_contact)) {
+        // Every classification below is SKIPPED on a cache hit, which is the single
+        // most confusing thing about the result: the contact inherits a verdict that
+        // was reached for an earlier contact on the same address or domain.
+        await activity('classification_reused', { from_cache: true, key: email.toLowerCase(), account_type: cached_contact.account_type, business_name: cached_contact?.business_info?.business_name, is_spam: cached_contact.is_spam });
+      }
 
       if (_.isEmpty(cached_contact)) {
         if (!is_spam && metadata.subject && !metadata.is_sent && !metadata.is_answered && !metadata.not_junk) {
           // deep search for spam
           is_spam = await ai_ms.is_spam_email(uid, email, metadata.subject, account_profile_info);
+          await activity('spam_check', { by: 'ai', is_spam: !!is_spam, subject: metadata.subject });
         }
         if (!is_spam) {
-          const is_business = await ai_ms.is_business_contact(uid, email, name, metadata.subject, metadata.summarized_body, account_profile_info);
+          const verdict = await ai_ms.is_business_contact(uid, email, name, metadata.subject, metadata.summarized_body, account_profile_info);
+          // Tolerates the old bare boolean, in case a stale ai_module answers this call.
+          const is_business = typeof verdict === 'object' && verdict !== null ? verdict.is_business : !!verdict;
           account_type = is_business ? 'business' : 'personal';
+          await activity('classified', { by: 'ai', account_type, confidence: verdict?.confidence, why: verdict?.reason, inputs: { email: email.toLowerCase(), name: name || '', subject: metadata.subject || '' } });
           if (is_business) {
             business_info = await ai_ms.get_business_info(uid, '', email, account_profile_info, { light: true });
-            if (business_info.business_name !== 'Not available') {
+            if (business_info.business_name !== 'Not available' && !businessIsJustTheMailProvider(business_info)) {
+              await activity('business_info', { by: 'ai', depth: 'light', business_name: business_info.business_name, business_domain: business_info.business_domain, business_category: business_info.business_category });
               business_has_person = await ai_ms.is_business_contact_has_person(uid, email, name, metadata.subject, metadata.summarized_body, account_profile_info);
+              await activity('business_has_person', { by: 'ai', has_person: !!business_has_person });
             } else {
+              const provider = identifyPersonalProvider(business_info?.business_domain || '');
               account_type = 'personal';
               business_info = undefined;
+              // The reversal matters more than the original verdict: the card says
+              // personal even though the business call answered yes.
+              await activity('classified', { by: 'ai', account_type, reverted_from: 'business', reason: provider ? `the only business behind the address is its mail provider (${provider})` : 'no business could be identified behind the address' });
             }
           }
           if (_.isEmpty(cached_contact) && account_type === 'business' && !business_has_person) {
@@ -5708,6 +5678,9 @@ export const add_contact = async function (req, job_id, headers) {
             } else {
               cached_contact = await get_xuda_cache(uid, 'contact', business_info.business_name, 'metadata');
             }
+            if (!_.isEmpty(cached_contact)) {
+              await activity('classification_reused', { from_cache: true, key: business_info.business_domain || business_info.business_name, account_type: cached_contact.account_type, business_name: cached_contact?.business_info?.business_name });
+            }
           }
         }
       }
@@ -5715,7 +5688,7 @@ export const add_contact = async function (req, job_id, headers) {
 
     const d = Date.now();
     const contact_obj = {
-      _id: await _common.xuda_get_uuid('contact'),
+      _id: contact_id,
       email: email.toLowerCase(),
       name: cached_contact?.name || name,
       stat: stat || 3,
@@ -5742,13 +5715,16 @@ export const add_contact = async function (req, job_id, headers) {
     if (!is_spam) {
       if (account_type === 'personal' || contact_obj?.business_has_person) {
         contact_obj.person_info = await ai_ms.get_person_info(uid, contact_obj.name, contact_obj.email, account_profile_info, metadata?.summarized_body, { light: true });
+        await activity('person_info', { by: 'ai', depth: 'light', full_name: contact_obj.person_info?.full_name, job_title: contact_obj.person_info?.job_title, company: contact_obj.person_info?.company_name });
         if (!contact_obj.name) {
           contact_obj.name = await ai_ms.get_name_from_email_addr(uid, contact_obj.email, account_profile_info);
+          await activity('name_resolved', { by: 'ai', from: 'email address', name: contact_obj.name });
         }
       }
 
       const conversation_obj = await ai_ms.create_openai_conversation();
       contact_obj.contact_reference_conversation_id = conversation_obj.id;
+      await activity('ai_thread_opened', { conversation_id: conversation_obj.id });
     } else {
       if (!contact_obj.name) {
         contact_obj.name = '';
@@ -5758,6 +5734,10 @@ export const add_contact = async function (req, job_id, headers) {
     const save_ret = await save_contact(uid, contact_obj);
     save_xuda_cache(uid, 'contact', contact_obj.email, null, contact_obj);
 
+    // The saved verdict, in one row, so the trail ends on the answer the card
+    // actually shows rather than making the reader replay the steps above.
+    await activity('saved', { account_type: contact_obj.account_type || 'unset', is_spam: !!contact_obj.is_spam, business_name: contact_obj?.business_info?.business_name, name: contact_obj.name || '' });
+
     if (!contact_obj.is_spam && contact_obj.name) {
       set_contact_profile_picture(uid, contact_obj._id, metadata, job_id, headers, account_profile_info, false);
     }
@@ -5821,6 +5801,7 @@ const set_contact_profile_picture = async function (uid, contact_id, metadata, j
         contact_obj.profile_picture_source = file_ret.profile_picture_source;
 
         const contact_save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_obj);
+        log_contact_activity(uid, contact_id, 'picture_found', { by: cache ? 'cache' : 'ai', source: file_ret.profile_picture_source, account_type: contact_obj.account_type || 'unset' });
         // profile_picture = contact_obj.profile_picture;
       }
     }
@@ -5905,10 +5886,14 @@ const set_contact_profile_picture = async function (uid, contact_id, metadata, j
       contact_obj.profile_avatar = contact_obj?.profile_avatar_obj?.file_url;
       contact_obj.avatar_source = file_ret?.data?.avatar_source;
       const contact_save_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_obj);
+      log_contact_activity(uid, contact_id, 'avatar_ready', { by: cache ? 'cache' : 'ai', source: contact_obj.avatar_source, account_type: contact_obj.account_type || 'unset' });
     }
     await update_contact_profile_picture_status(uid, contact_id, 3);
   } catch (err) {
     await update_contact_profile_picture_status(uid, contact_id, 1, err.message);
+    // Worth a row of its own: a contact stuck on the shop / silhouette placeholder
+    // looks like a classification result, and this is the line that says otherwise.
+    log_contact_activity(uid, contact_id, 'picture_failed', { error: err?.message });
     delete_xuda_cache(contact_obj);
   }
 };
@@ -6141,6 +6126,7 @@ export const archive_contact = async function (req) {
     contact_doc.stat_reason = 'archived by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'archived', { by: 'user', reason: contact_doc.stat_reason });
 
     return contact_save_ret;
   } catch (err) {
@@ -6163,6 +6149,7 @@ export const delete_contact = async function (req, job_id, headers) {
     contact_doc.stat_reason = 'deleted by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'deleted', { by: 'user', reason: contact_doc.stat_reason, note: 'conversations attached to this contact were deleted with it' });
 
     ai_msa.delete_depended_chats(uid, contact_id);
     return contact_save_ret;
@@ -6188,6 +6175,7 @@ export const unarchive_contact = async function (req, job_id, headers) {
     contact_doc.stat_reason = 'unarchive by the user';
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unarchived', { by: 'user', reason: contact_doc.stat_reason });
 
     if (!contact_doc.is_spam) {
       not_spam_contact(req, job_id, headers);
@@ -6217,6 +6205,7 @@ export const unfriend_contact = async function (req) {
 
     contact_doc.team_req_id = null;
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unfriended', { by: 'user' });
 
     const req_save_ret = await db_module.save_couch_doc('xuda_team', req_doc);
 
@@ -6236,6 +6225,7 @@ export const pin_contact = async function (req) {
     contact_doc.pinned = true;
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'pinned', { by: 'user' });
 
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'contact_pinned',
@@ -6280,6 +6270,7 @@ export const unpin_contact = async function (req) {
     contact_doc.pinned = false;
 
     const contact_save_ret = await save_contact(uid, contact_doc);
+    log_contact_activity(uid, contact_id, 'unpinned', { by: 'user' });
 
     ws_dashboard_msa.emit_message_to_dashboard({
       service: 'contact_unpinned',
@@ -6311,22 +6302,42 @@ export const not_spam_contact = async function (req, job_id, headers) {
         stat: 3,
       });
     }
+    const was_spam = !!contact_doc.is_spam;
     contact_doc.is_spam = false;
+    log_contact_activity(uid, contact_id, 'marked_not_spam', { by: 'user', was_spam, note: was_spam ? 'address added to the spam whitelist, classification is being redone' : 'classification is being redone' });
 
     if (!contact_doc.contact_reference_conversation_id) {
       const conversation_obj = await ai_ms.create_openai_conversation();
       contact_doc.contact_reference_conversation_id = conversation_obj.id;
+      await log_contact_activity(uid, contact_id, 'ai_thread_opened', { conversation_id: conversation_obj.id });
     }
 
-    const is_business = await ai_ms.is_business_contact(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+    const previous_account_type = contact_doc.account_type;
+    const verdict = await ai_ms.is_business_contact(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+    const is_business = typeof verdict === 'object' && verdict !== null ? verdict.is_business : !!verdict;
     contact_doc.account_type = is_business ? 'business' : 'personal';
+    await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', trigger: 'not spam', account_type: contact_doc.account_type, confidence: verdict?.confidence, why: verdict?.reason, previous_account_type: previous_account_type || 'unset' });
+    if (!is_business && (contact_doc.business_info || contact_doc.business_has_person)) {
+      // A contact that reclassifies from business to person used to keep the company profile
+      // the old verdict attached to it, because business_info is only ever written inside the
+      // is_business branch and nothing clears it on the way out. The card then showed a person
+      // with a company still on file.
+      const dropped = contact_doc?.business_info?.business_name;
+      contact_doc.business_info = undefined;
+      contact_doc.business_has_person = undefined;
+      await log_contact_activity(uid, contact_id, 'business_info_cleared', { reason: 'contact reclassified as a person', dropped });
+    }
     if (is_business) {
       contact_doc.business_info = await ai_ms.get_business_info(uid, '', contact_doc.email, account_profile_info, { light: true });
-      if (contact_doc.business_info.business_name !== 'Not available') {
+      if (contact_doc.business_info.business_name !== 'Not available' && !businessIsJustTheMailProvider(contact_doc.business_info)) {
+        await log_contact_activity(uid, contact_id, 'business_info', { by: 'ai', depth: 'light', business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
         contact_doc.business_has_person = await ai_ms.is_business_contact_has_person(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'business_has_person', { by: 'ai', has_person: !!contact_doc.business_has_person });
       } else {
+        const provider = identifyPersonalProvider(contact_doc.business_info?.business_domain || '');
         contact_doc.account_type = 'personal';
         contact_doc.business_info = undefined;
+        await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', account_type: 'personal', reverted_from: 'business', reason: provider ? `the only business behind the address is its mail provider (${provider})` : 'no business could be identified behind the address' });
       }
     }
 
@@ -6362,6 +6373,7 @@ export const not_spam_contact = async function (req, job_id, headers) {
       req.email_id = email._id;
       await email_ms.process_pending_email(req, job_id, headers);
     }
+    if (emails.docs.length) log_contact_activity(uid, contact_id, 'emails_reprocessed', { count: emails.docs.length, trigger: 'not spam', note: 'partially processed emails were re-read in full' });
 
     return contact_save_ret;
   } catch (err) {
@@ -6390,6 +6402,7 @@ export const generate_contact_avatar = async function (req, job_id, headers) {
 
     const contact_save_ret = await save_contact(uid, contact_doc);
     await delete_xuda_cache(contact_doc);
+    log_contact_activity(uid, contact_id, 'avatar_regenerate_requested', { by: 'user', note: 'existing picture and avatar cleared, a new avatar is being generated' });
     set_contact_profile_picture(uid, contact_doc._id, {}, job_id, headers, account_profile_info, true);
 
     return contact_save_ret;
@@ -6407,21 +6420,28 @@ export const set_deep_research_contact = async function (req, job_id, headers) {
   try {
     var contact_doc = await get_contact(uid, contact_id);
     contact_doc.deep_research = true;
+    await log_contact_activity(uid, contact_id, 'deep_research_started', { by: 'user', account_type: contact_doc.account_type || 'unset' });
 
     if (contact_doc.account_type === 'business') {
       contact_doc.business_info = await ai_ms.get_business_info(uid, '', contact_doc.email, account_profile_info);
-      if (contact_doc.business_info.business_name !== 'Not available') {
+      if (contact_doc.business_info.business_name !== 'Not available' && !businessIsJustTheMailProvider(contact_doc.business_info)) {
+        await log_contact_activity(uid, contact_id, 'business_info', { by: 'ai', depth: 'deep', business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
         contact_doc.business_has_person = await ai_ms.is_business_contact_has_person(uid, contact_doc.email, contact_doc.name, contact_doc?.metadata?.subject, contact_doc?.metadata?.summarized_body, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'business_has_person', { by: 'ai', has_person: !!contact_doc.business_has_person });
       } else {
+        const provider = identifyPersonalProvider(contact_doc.business_info?.business_domain || '');
         contact_doc.account_type = 'personal';
         contact_doc.business_info = undefined;
+        await log_contact_activity(uid, contact_id, 'classified', { by: 'ai', account_type: 'personal', reverted_from: 'business', reason: provider ? `the only business behind the address is its mail provider (${provider})` : 'deep research found no business behind the address' });
       }
     }
 
     if (contact_doc.account_type === 'personal' || contact_doc?.business_has_person) {
       contact_doc.person_info = await ai_ms.get_person_info(uid, contact_doc.name, contact_doc.email, account_profile_info, contact_doc?.metadata?.summarized_body);
+      await log_contact_activity(uid, contact_id, 'person_info', { by: 'ai', depth: 'deep', full_name: contact_doc.person_info?.full_name, job_title: contact_doc.person_info?.job_title, company: contact_doc.person_info?.company_name });
       if (!contact_doc.name) {
         contact_doc.name = await ai_ms.get_name_from_email_addr(uid, contact_doc.email, account_profile_info);
+        await log_contact_activity(uid, contact_id, 'name_resolved', { by: 'ai', from: 'email address', name: contact_doc.name });
       }
     }
 
@@ -6456,6 +6476,8 @@ export const set_deep_research_contact = async function (req, job_id, headers) {
         throw err;
       }
     }
+    if (conversation_items.docs.length) log_contact_activity(uid, contact_id, 'attachments_transcribed', { count: conversation_items.docs.length, trigger: 'deep research' });
+    log_contact_activity(uid, contact_id, 'deep_research_finished', { account_type: contact_doc.account_type || 'unset', business_name: contact_doc?.business_info?.business_name });
 
     return contact_save_ret;
   } catch (err) {
@@ -6475,6 +6497,7 @@ export const unset_deep_research_contact = async function (req, job_id, headers)
 
     const contact_save_ret = await save_contact(uid, contact_doc);
     await delete_xuda_cache(contact_doc);
+    log_contact_activity(uid, contact_id, 'deep_research_turned_off', { by: 'user' });
 
     return contact_save_ret;
   } catch (err) {
@@ -6484,6 +6507,89 @@ export const unset_deep_research_contact = async function (req, job_id, headers)
     };
   }
 };
+
+// The trail for one contact, newest first.
+//
+// Recorded rows are only half the answer: every contact that existed before the
+// trail did has none, and those are most of them. So the contact doc is read back
+// into the same shape first (derived: true). The doc keeps one timestamp per
+// FIELD, not per step, so a derived row is stamped with the closest timestamp it
+// honestly has (date_created for the creation and the classification that ran
+// inside it, profile_avatar_stat_ts for the picture, stat_ts for the archive) and
+// says derived so the UI can mark it as reconstructed rather than observed.
+export const get_contact_activity = async function (req) {
+  const { uid, contact_id } = req;
+  try {
+    if (!contact_id) throw new Error('contact_id is missing');
+    const account_profile_info = await get_active_account_profile_info(uid);
+    // get_app_couch_doc_native THROWS a bare couch 'missing' for an id that is not in
+    // this account's app db (an id from another account is the common way to get here),
+    // so the not-found check below never ran and the caller saw "missing" with nothing
+    // to act on. Catch it and answer the question that was actually asked.
+    let contact_doc;
+    try {
+      contact_doc = await db_module.get_app_couch_doc_native(account_profile_info.app_id, contact_id);
+    } catch (_) {
+      contact_doc = null;
+    }
+    if (!contact_doc || contact_doc.docType !== 'contact') throw new Error(`contact ${contact_id} not found`);
+    if (contact_doc.uid !== uid && contact_doc?.uid_created !== uid) throw new Error('Operation not allowed');
+
+    const recorded_ret = await db_module.find_app_couch_query(account_profile_info.app_id, {
+      selector: { docType: 'contact_activity', contact_id },
+      limit: 500,
+    });
+    const recorded = (recorded_ret?.docs || []).map((d) => ({ event: d.event, detail: d.detail || {}, ts: d.ts, derived: false }));
+
+    const derived = [];
+    const add = (event, ts, detail) => {
+      if (!ts) return;
+      // A recorded row always wins: it has the real timestamp and the real inputs.
+      if (recorded.some((r) => r.event === event)) return;
+      derived.push({ event, detail, ts, derived: true });
+    };
+
+    const created_ts = contact_doc.date_created || contact_doc.ts;
+    add('created', created_ts, { source: contact_doc.source || 'unknown', email: contact_doc.email, name: contact_doc.name || '', from_account: !!contact_doc.contact_uid, subject: contact_doc?.metadata?.subject });
+    if (contact_doc.is_spam) add('spam_check', created_ts, { is_spam: true });
+    if (contact_doc.account_type) add('classified', created_ts, { account_type: contact_doc.account_type });
+    if (contact_doc?.business_info?.business_name) add('business_info', created_ts, { business_name: contact_doc.business_info.business_name, business_domain: contact_doc.business_info.business_domain, business_category: contact_doc.business_info.business_category });
+    if (contact_doc.business_has_person !== undefined && contact_doc.business_has_person !== null) add('business_has_person', created_ts, { has_person: !!contact_doc.business_has_person });
+    if (contact_doc?.person_info) add('person_info', created_ts, { full_name: contact_doc.person_info.full_name || contact_doc.person_info.person_full_name, job_title: contact_doc.person_info.job_title, company: contact_doc.person_info.company_name });
+    if (contact_doc.contact_reference_conversation_id) add('ai_thread_opened', created_ts, { conversation_id: contact_doc.contact_reference_conversation_id });
+    if (contact_doc.profile_picture) add('picture_found', contact_doc.profile_avatar_stat_ts || created_ts, { source: contact_doc.profile_picture_source });
+    if (contact_doc.profile_avatar) add('avatar_ready', contact_doc.profile_avatar_stat_ts || created_ts, { source: contact_doc.avatar_source });
+    if (contact_doc.profile_avatar_stat === 1 && contact_doc.profile_avatar_error) add('picture_failed', contact_doc.profile_avatar_stat_ts, { error: contact_doc.profile_avatar_error });
+    if (contact_doc.deep_research) add('deep_research_started', contact_doc.stat_ts || created_ts, {});
+    if (contact_doc.pinned) add('pinned', contact_doc.stat_ts || created_ts, {});
+    // stat carries only the LAST transition, which is why an archive/unarchive
+    // history is exactly what the recorded trail adds from here on.
+    if (contact_doc.stat === 5) add('archived', contact_doc.stat_ts, { reason: contact_doc.stat_reason });
+    if (contact_doc.stat === 4) add('deleted', contact_doc.stat_ts, { reason: contact_doc.stat_reason });
+
+    const rows = [...recorded, ...derived].sort((a, b) => (b.ts || 0) - (a.ts || 0));
+
+    return {
+      code: 1,
+      data: {
+        contact_id,
+        // What the card shows today, so the UI can head the trail with the outcome.
+        current: {
+          account_type: contact_doc.account_type || null,
+          is_spam: !!contact_doc.is_spam,
+          stat: contact_doc.stat,
+          source: contact_doc.source || null,
+          deep_research: !!contact_doc.deep_research,
+          business_name: contact_doc?.business_info?.business_name || null,
+          profile_avatar_stat: contact_doc.profile_avatar_stat,
+        },
+        rows,
+      },
+    };
+  } catch (err) {
+    return { code: -25, data: err.message };
+  }
+};
 //////// PROFILES  //////////////
 
 export const get_pending_share_profile_in = async function (uid, _id) {
@@ -6545,7 +6651,11 @@ export const get_account_profile_info = async function (uid, contact_profile_doc
 
   const get_pattern = async function (doc) {
     // Same level-based default as get_contact_pattern, so a card shows the same
-    // verification tile whichever path built it.
+    // verification tile whichever path built it, and the same two states that
+    // outrank a level: a shared profile wears its owner's avatar, spam says
+    // spam. A business profile used to paint its own logo across the card face,
+    // which is why a verified business showed no level at all; the logo is
+    // already the avatar on the same card, so the tile is the level here too.
     let ret = level_pattern(doc);
 
     if (doc.shared_from_uid) {
@@ -6554,26 +6664,6 @@ export const get_account_profile_info = async function (uid, contact_profile_doc
       ret = shared_from_uid_ret.data.profile_avatar;
     } else if (doc.is_spam) {
       ret = `spam-pattern.png`;
-    } else if (doc.account_type === 'business') {
-      ret = doc.profile_picture;
-    } else {
-      switch (doc.avatar_source) {
-        case 'fictional':
-          ret = `fictional-avatar-pattern.png`;
-          break;
-
-        case 'ai profile':
-          ret = `fictional-avatar-pattern.png`;
-          break;
-
-        case 'authentic profile':
-          ret = `authentic-avatar-pattern.png`;
-          break;
-
-        default:
-          ret = `xu-pattern.png`;
-          break;
-      }
     }
 
     return ret;
@@ -6631,6 +6721,10 @@ export const get_account_profile_info = async function (uid, contact_profile_doc
   // console.log(stringToColour('Project Z')); // -> Consistent color for "Project Z"
 
   doc.avatar_source = account_info_ret.data.avatar_source;
+  // A profile inherits the verification level of the account that owns it (a
+  // shared profile, the account that shared it), so its card reads the same
+  // level as its owner's contact card instead of falling back to L0.
+  doc.verify_level = account_info_ret.data.verify_level;
   doc.icon_pattern = await get_pattern(doc);
   doc.name = doc.profile_name;
   doc.interactions = 0;
@@ -7030,6 +7124,48 @@ export const get_contact = async function (uid, contact_id) {
   return contact_ret;
 };
 
+// ---------------------------------------------------------------------------
+// Contact activity trail
+//
+// A contact accumulates a lot of history that was previously only visible as
+// the END STATE on its own doc: it was created from somewhere, several AI steps
+// ran on it and each decided something (spam, business or personal, the business
+// profile, the person profile, the name, the avatar), and it may since have been
+// archived, unarchived, pinned, re-classified or sent to deep research. The doc
+// keeps the last answer of each and nothing about when, in what order, or what
+// the previous answer was, so "why is this contact a business" had no trace to
+// read back.
+//
+// One `contact_activity` doc per event, in the same app db as the contact.
+// Deliberately append-only and deliberately silent: a failure to WRITE the trail
+// must never fail the action being recorded, so every call is wrapped and logged
+// to the console instead of thrown. Callers do not await it for that reason
+// either, except where the next line already awaits something else anyway.
+// ---------------------------------------------------------------------------
+const log_contact_activity = async function (uid, contact_id, event, detail = {}, app_id) {
+  try {
+    if (!uid || !contact_id || !event) return null;
+    const app = app_id || (await get_active_account_profile_info(uid))?.app_id;
+    if (!app) return null;
+
+    return await db_module.save_app_couch_doc_native(app, {
+      _id: await _common.xuda_get_uuid('contact_activity'),
+      docType: 'contact_activity',
+      contact_id,
+      uid,
+      event,
+      // Values the UI prints back verbatim, so keep them short and human. Never
+      // put a full AI response or an email body here: the trail is a summary.
+      detail,
+      ts: Date.now(),
+      stat: 3,
+    });
+  } catch (err) {
+    console.error('[account_module] contact activity not recorded:', event, contact_id, err?.message);
+    return null;
+  }
+};
+
 export const save_contact = async function (uid, contact_doc) {
   const account_profile_info = await get_active_account_profile_info(uid);
   const contact_ret = await db_module.save_app_couch_doc(account_profile_info.app_id, contact_doc);

package/index_ms.mjs

@@ -449,6 +449,10 @@ export const unset_deep_research_contact = async function (...args) {
   return await broker.send_to_queue("unset_deep_research_contact", ...args);
 };
 
+export const get_contact_activity = async function (...args) {
+  return await broker.send_to_queue("get_contact_activity", ...args);
+};
+
 export const get_pending_share_profile_in = async function (...args) {
   return await broker.send_to_queue("get_pending_share_profile_in", ...args);
 };

package/index_msa.mjs

@@ -449,6 +449,10 @@ export const unset_deep_research_contact =  function (...args) {
    broker.send_to_queue_async("unset_deep_research_contact", ...args);
 };
 
+export const get_contact_activity =  function (...args) {
+   broker.send_to_queue_async("get_contact_activity", ...args);
+};
+
 export const get_pending_share_profile_in =  function (...args) {
    broker.send_to_queue_async("get_pending_share_profile_in", ...args);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xuda.io/account_module",
-  "version": "1.2.2309",
+  "version": "1.2.2311",
   "description": "Xuda Account Server Module",
   "main": "index.mjs",
   "dependencies": {