@xuda.io/account_module 1.2.2312 → 1.2.2314

package/index.mjs

@@ -144,9 +144,40 @@ export const _sync_account_project_name = async function (account_obj, ref_info)
 // stat 1 is the unverified state (stat 2 is the password-reset temp state,
 // stat 3 verified), matching the write-gate in http_module — which now lets
 // update_account_info and upload_drive_file_user through at stat 1 precisely so
-// the picture can be saved. verify_account starts any deferred generation the
-// moment the account flips to verified, so nothing is lost by waiting here.
-const can_generate_avatar = (account_obj) => account_obj?.stat !== 1;
+// the picture can be saved.
+//
+// The bar is LEVEL 2, not a confirmed email. A Xuda avatar is a portrait shown
+// beside a name across the platform, and level 2 is the first level that checks
+// a face against a photo ID — so it is the first point at which the portrait can
+// be said to be of the person it claims to be. Below it the account keeps its
+// uploaded picture and simply has no generated avatar. verify_module fires
+// ensure_profile_avatar the moment an account crosses into level 2, so nothing
+// is lost by waiting here.
+//
+// verify_level is the projection _recompute writes onto the account doc, so this
+// reads the same number every other surface reads and needs no round trip.
+const AVATAR_MIN_VERIFY_LEVEL = 2;
+const can_generate_avatar = (account_obj) => account_obj?.stat !== 1 && Number(account_obj?.account_info?.verify_level || 0) >= AVATAR_MIN_VERIFY_LEVEL;
+
+// Is an avatar owed for the picture currently on the account?
+//
+// The test is against the SOURCE, not against profile_avatar. Several client
+// paths mirror the uploaded photo into profile_avatar so that every surface
+// shows the new face immediately instead of a placeholder while generation
+// runs, which makes "has an avatar" useless as a question — the field is
+// populated either way. profile_avatar_from records the picture the generated
+// avatar was actually made from, and it is written by the generator alone (it is
+// deliberately absent from account_info_properties, so no client can set it).
+//
+// That is what makes this safe to evaluate on every save: replacing the photo
+// makes an avatar due exactly once, and nothing the client writes into
+// profile_avatar can make it due a second time.
+const avatar_is_due = (account_info) => {
+  const info = account_info || {};
+  if (!info.profile_picture) return false;
+  if (info.profile_avatar_stat === 2) return false; // one is already generating
+  return info.profile_avatar_from !== info.profile_picture;
+};
 
 export const update_account_info = async function (req, job_id, headers) {
   const { uid } = req;
@@ -184,6 +215,19 @@ export const update_account_info = async function (req, job_id, headers) {
   var account_info_changes_arr = [];
   var error = {};
 
+  // The client sends active_account_profile_id straight from its own store, and that store can
+  // hold a profile belonging to a DIFFERENT account (e.g. after switching accounts in the
+  // dashboard). Writing a foreign id here used to brick the account: every later read of the
+  // profile looked it up in THIS account's project db, got "missing", and threw. Only accept an
+  // id that actually resolves to an account_profile in this account's own project.
+  if (typeof data.active_account_profile_id !== 'undefined' && data.active_account_profile_id !== account_obj.account_info?.active_account_profile_id) {
+    const candidate_profile = await _try_get_profile_doc(account_obj.account_project_id, data.active_account_profile_id);
+    if (!candidate_profile) {
+      console.warn(`[update_account_info] acc ${uid}: rejected active_account_profile_id ${data.active_account_profile_id}, not an account_profile in project ${account_obj.account_project_id}`);
+      delete data.active_account_profile_id;
+    }
+  }
+
   await marketplace_ms.marketplace_save_user({ uid });
 
   for (const key of account_info_properties) {
@@ -287,12 +331,31 @@ export const update_account_info = async function (req, job_id, headers) {
     return { code: -1310, data: error };
   }
   if (!change) {
-    if (can_generate_avatar(account_obj) && account_obj.account_info?.profile_picture && !account_obj.account_info?.profile_avatar && account_obj.account_info.profile_avatar_stat !== 2) {
+    // A no-op save still gets to start a generation that is owed. This is the
+    // path a verified account takes when it reopens the picture window and
+    // presses through without changing anything, and it is how an account that
+    // reached level 2 before this rule existed picks up its avatar.
+    if (can_generate_avatar(account_obj) && avatar_is_due(account_obj.account_info)) {
       set_account_profile_picture(uid, uid, account_obj.account_info, job_id, headers, account_profile_info);
     }
     return { code: 1300, data: 'no change' };
   }
 
+  // A client that sets profile_avatar to something OTHER than the photo itself
+  // is recording a GENERATED avatar — the create_avatar route the picture window
+  // and the onboarding step drive, which hands the file back to the browser and
+  // saves nothing itself. Stamping the source here is what stops that avatar
+  // reading as still owed, which would have the server generate a second one
+  // over the top of it on the next save, at the cost of the AI credits twice.
+  //
+  // Mirroring the photo INTO profile_avatar is the opposite case: a placeholder
+  // so surfaces show the new face immediately, with a real avatar still owed.
+  // The two are told apart by exactly that — whether the avatar is the photo.
+  if (account_info_changes_arr.includes('profile_avatar') && account_obj.account_info.profile_avatar && account_obj.account_info.profile_avatar !== account_obj.account_info.profile_picture) {
+    account_obj.account_info.profile_avatar_from = account_obj.account_info.profile_picture;
+    account_obj.account_info.avatar_source = account_obj.account_info.profile_avatar_obj?.avatar_source || account_obj.account_info.avatar_source;
+  }
+
   account_obj.account_info.full_name = `${account_obj.account_info.first_name} ${account_obj.account_info.last_name}`;
 
   //clean up received from req
@@ -326,10 +389,11 @@ export const update_account_info = async function (req, job_id, headers) {
     await _sync_account_project_name(account_obj, _old_name_info);
   }
 
-  if (can_generate_avatar(account_obj) && account_obj.account_info?.profile_picture) {
-    if (!account_obj.account_info?.profile_avatar && account_obj.account_info.profile_avatar_stat !== 2) {
-      set_account_profile_picture(uid, uid, account_obj.account_info, job_id, headers, account_profile_info);
-    }
+  // A new photo makes the avatar on file stale, so this covers the ordinary
+  // "changed my picture" case as well as the first-ever generation: both are
+  // just "the avatar was not made from the picture that is there now".
+  if (can_generate_avatar(account_obj) && avatar_is_due(account_obj.account_info)) {
+    set_account_profile_picture(uid, uid, account_obj.account_info, job_id, headers, account_profile_info);
   }
 
   // Opportunistic Stripe consolidation. Any time the user updates
@@ -606,8 +670,20 @@ export const get_effective_entitlements = function (account_doc) {
 //                    to where it is set.
 // scope 'metered'  → no plan ladder at all, usage is metered per call. Listed
 //                    so the customer can see it costs no subscription.
+//
+// `is_active`   → the module is being PAID for. Defaults to price > 0.
+// `is_activated`→ the customer switched it ON, Free included. Defaults to
+//                 `is_active` or a `<field>_changed` stamp, and a module that
+//                 keeps its own answer to that question says so here rather
+//                 than leaving the UI to guess from a price of zero.
 const _MODULE_SUBSCRIPTIONS = [
-  { key: 'commerce', scope: 'account', field: 'commerce_plan', default_plan: 'commerce_free' },
+  // UI-192: `commerce_plan` being SET at all is Commerce's own on/off switch
+  // (`chosen` in commerce_module _cm_plan), which is why activation is read off
+  // the field rather than off the stamp: commerce_set_plan wrote the plan and
+  // stamped nothing until this same change, so every account that switched
+  // Commerce on at its free tier reported "not switched on" here while its own
+  // screen showed the stores.
+  { key: 'commerce', scope: 'account', field: 'commerce_plan', default_plan: 'commerce_free', is_activated: (a) => !!a.commerce_plan },
   { key: 'shipping', scope: 'account', field: 'shipping_plan', default_plan: 'shipping_free' },
   { key: 'finance', scope: 'account', field: 'finance_plan', default_plan: 'finance_free' },
   // The desk screen has its own copy of this ladder (UI-82), because Tickets is
@@ -617,12 +693,17 @@ const _MODULE_SUBSCRIPTIONS = [
   // UI-104: email is its own product, billed per mailbox tier. Its plan lives on the
   // account as an OBJECT (`email_plan.tier`), which is why it resolves rather than
   // reading a field, and `set_email_plan` is what moves it.
+  // UI-192: and its "the customer chose this" marker is `email_plan.activated_ts`, not
+  // an `email_plan_changed` field, which is email_policy's own `chosen`. The generic
+  // stamp lookup never found anything, so an account on a deliberately free mailbox
+  // tier read as switched off.
   {
     key: 'email',
     scope: 'account',
     field: 'email_plan',
     default_plan: 'email_free',
     resolve: (a) => (a && a.email_plan && a.email_plan.tier ? `email_${a.email_plan.tier}` : ''),
+    changed_of: (a) => (a && a.email_plan && a.email_plan.activated_ts) || null,
   },
   // Auto response is the single gate for whether the AI answers, on every channel
   // (chat, the public chat widget, email and the phone). It is account scoped and
@@ -888,9 +969,14 @@ export const get_module_subscriptions = async function (req = {}) {
         // `plan_of` keeps reporting no plan, exactly as before.
         const plan_id = m.plan_of ? m.plan_of(account) : '';
         const plan = plans[plan_id] || {};
+        const active = m.is_active ? !!m.is_active(account, base.items) : m.scope === 'metered' || base.items.length > 0;
         return {
           ...base,
-          active: m.is_active ? !!m.is_active(account, base.items) : m.scope === 'metered' || base.items.length > 0,
+          active,
+          // UI-192: a per-resource module has no free tier to be switched on at, so
+          // paying for one of the things IS being switched on. Sent all the same, so
+          // every surface can ask the one question rather than two.
+          activated: m.is_activated ? !!m.is_activated(account, base.items) : active,
           included: m.scope === 'metered',
           plan_id,
           plan_name: plan.name || '',
@@ -913,6 +999,11 @@ export const get_module_subscriptions = async function (req = {}) {
         ? { to_plan: pc.to_plan, to_name: plans[pc.to_plan]?.name || pc.to_plan, effective: pc.effective || null }
         : null;
       const price = Number(plan.price) || 0;
+      // Every *_set_plan method stamps `<field>_changed` when the customer picks a
+      // tier, Free included, so this is the general answer to "have they been through
+      // the picker". A module whose marker is somewhere else brings its own resolver.
+      const changed_ts = (m.changed_of ? m.changed_of(account) : account[`${m.field}_changed`]) || null;
+      const active = m.is_active ? !!m.is_active(account, base.items) : price > 0;
       return {
         ...base,
         plan_id,
@@ -921,10 +1012,16 @@ export const get_module_subscriptions = async function (req = {}) {
         // UI-110: paying is the default proof that a module is on, but a module that
         // records the customer CHOOSING a tier says so itself, because a deliberate
         // free tier is switched on and a price of zero cannot tell the two apart.
-        active: m.is_active ? !!m.is_active(account, base.items) : price > 0,
+        active,
+        // UI-192 (Boaz, on the create sheet's switches): "switched on" as its own
+        // answer, so no surface has to reassemble it out of `active` and `changed_ts`
+        // and get it differently from the next one. Picking a FREE tier is switching
+        // the module on: it is a real tier, it opens the module's screen and it puts
+        // the module in the menu, and the switch that did it has to stay flipped.
+        activated: m.is_activated ? !!m.is_activated(account, base.items) : !!(active || changed_ts),
         included: false,
         pending,
-        changed_ts: account[`${m.field}_changed`] || null,
+        changed_ts,
       };
     });
     return { code: 1, data: { modules, membership_plan: account.membership_plan || 'free' } };
@@ -3410,6 +3507,20 @@ export const did_you_know_tips = async function (req, job_id, headers) {
 
 const _warned_no_account_project_id = new Set();
 const _warned_no_profile_id = new Set();
+const _warned_dangling_profile_id = new Set();
+
+// Resolve a profile doc that is supposed to live in this account's own project db, without
+// throwing when it does not. A dangling id is not an exceptional condition here: it happens
+// whenever a profile was deleted, or when an id belonging to ANOTHER account leaked into
+// account_info.active_account_profile_id (update_account_info used to accept any id the client
+// sent). Returning null lets the caller fall back instead of hard-failing every read.
+const _try_get_profile_doc = async function (app_id, doc_id) {
+  if (!app_id || !doc_id) return null;
+  const ret = await db_module.get_app_couch_doc(app_id, doc_id, true);
+  if (ret.code < 0) return null;
+  const doc = ret.data;
+  return doc && doc.docType === 'account_profile' ? doc : null;
+};
 
 export const get_active_account_profile_info = async function (uid, profile_id) {
   try {
@@ -3468,7 +3579,65 @@ export const get_active_account_profile_info = async function (uid, profile_id)
       return { uid, account_profile_id: null, app_id: acc_obj.account_project_id, is_main: false, account_profile_obj: null };
     }
 
-    const account_profile_obj = await db_module.get_app_couch_doc_native(acc_obj.account_project_id, active_account_profile_id);
+    let account_profile_obj = await _try_get_profile_doc(acc_obj.account_project_id, active_account_profile_id);
+
+    if (!account_profile_obj) {
+      // The stored id points at nothing in this account's project db (deleted profile, or a
+      // foreign id written by an older, unvalidated update_account_info). Previously this threw
+      // "missing" and every caller downstream, i.e. the whole AI workspace, died with it. Walk the
+      // rest of the fallback chain instead and repair the account doc so the next read is clean.
+      const candidates = [acc_obj.account_info?.active_account_profile_id, acc_obj.account_profile_id].filter((id) => id && id !== active_account_profile_id);
+
+      for (const candidate of candidates) {
+        account_profile_obj = await _try_get_profile_doc(acc_obj.account_project_id, candidate);
+        if (account_profile_obj) {
+          active_account_profile_id = candidate;
+          break;
+        }
+      }
+
+      if (!account_profile_obj) {
+        // Nothing on the account doc resolves. Adopt this account's own main (or newest) profile.
+        try {
+          const existing = await db_module.find_app_couch_query(acc_obj.account_project_id, {
+            selector: { docType: 'account_profile', uid },
+            limit: 50,
+          });
+          const docs = (existing && existing.docs) || [];
+          const chosen = docs.find((d) => d.main) || docs.slice().sort((a, b) => (b.date_created_ts || 0) - (a.date_created_ts || 0))[0];
+          if (chosen) {
+            account_profile_obj = chosen;
+            active_account_profile_id = chosen._id;
+          }
+        } catch (find_err) {
+          /* fall through to the soft-fail below */
+        }
+      }
+
+      if (!_warned_dangling_profile_id.has(acc_obj._id)) {
+        _warned_dangling_profile_id.add(acc_obj._id);
+        console.warn(`[get_active_account_profile_info] acc ${acc_obj._id}: profile not found in project ${acc_obj.account_project_id}; fell back to ${active_account_profile_id || 'null'}`);
+      }
+
+      if (!account_profile_obj) {
+        return { uid, account_profile_id: null, app_id: acc_obj.account_project_id, is_main: false, account_profile_obj: null };
+      }
+
+      // Persist the repair only when the bad id came from the account's own stored state. A bad
+      // explicit profile_id argument is the caller's problem, not something to write back.
+      if (!profile_id && acc_obj.account_info?.active_account_profile_id !== active_account_profile_id) {
+        try {
+          acc_obj.account_info = acc_obj.account_info || {};
+          acc_obj.account_info.active_account_profile_id = active_account_profile_id;
+          if (!acc_obj.account_profile_id) acc_obj.account_profile_id = active_account_profile_id;
+          await db_module.save_couch_doc('xuda_accounts', acc_obj); // conflict-safe (retry loop)
+          console.log(`[get_active_account_profile_info] self-healed acc ${acc_obj._id}: active profile reset to ${active_account_profile_id}`);
+        } catch (heal_err) {
+          /* the in-memory fallback above still serves this request */
+        }
+      }
+    }
+
     if (account_profile_obj.share_item_id) {
       // set the original profile id if shared
       active_account_profile_id = account_profile_obj.share_item_id;
@@ -3645,13 +3814,14 @@ export const verify_account = async function (req) {
     console.warn('[verify_account] confirm_email banner cleanup failed:', e.message);
   }
 
-  // A picture uploaded before verification deliberately did NOT generate an
-  // avatar (see can_generate_avatar). The account is verified as of the save
-  // above, so start the generation that was deferred. Fire-and-forget:
-  // generation is heavy (vision + image ops) and must not hold up the verify
-  // response, and ensure_profile_avatar re-reads the doc and does its own
-  // guarding — picture present, no avatar yet, not already generating — so a
-  // user who never uploaded one is a no-op.
+  // Confirming an email no longer earns an avatar on its own — level 2 does,
+  // and verify_module starts the generation when the account crosses it. This
+  // call stays because it costs nothing and closes the one ordering it would
+  // otherwise miss: an account that already holds level 2 while still sitting at
+  // stat 1, where can_generate_avatar refused up to the save above. For everyone
+  // else ensure_profile_avatar re-reads the doc, finds the level bar unmet, and
+  // returns. Fire-and-forget either way: generation is heavy (vision + image
+  // ops) and must not hold up the verify response.
   try {
     ensure_profile_avatar({ uid: account_id }).catch((e) => console.warn('[verify_account] deferred avatar start failed:', e.message));
   } catch (e) {
@@ -4311,15 +4481,23 @@ 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.
+// Where a contact comes from decides which language its tile speaks, and the two
+// are not interchangeable.
+//
+// A contact with a `contact_uid` is a real Xuda account, so its tile is that
+// account's verification level. This used to be computed and then thrown away by
+// a switch on `avatar_source` that returned the generic xu tile, which is why a
+// card for a verified person showed no level at all.
+//
+// A contact with no account behind it has no level and must never be given one,
+// not even L0: nobody scored that person, and a card that says otherwise is a
+// claim we cannot back. Those keep the tile for where they walked in from, the
+// mailbox, the web, or an incoming call.
+//
+// Ahead of both, the states that mean the card cannot show either: a shared card
+// wears its owner's avatar, an avatar mid-processing says so, spam says spam.
 const get_contact_pattern = async function (doc) {
-  let ret = level_pattern(doc);
+  let ret = `default-pattern.png`;
 
   if (doc?.shared_from_uid) {
     const shared_from_uid_ret = await get_account_name({ uid_query: doc.shared_from_uid });
@@ -4338,12 +4516,34 @@ const get_contact_pattern = async function (doc) {
     }
   } else if (doc.is_spam) {
     ret = `spam-pattern.png`;
+  } else if (doc.contact_uid) {
+    ret = level_pattern(doc);
+  } else {
+    switch (doc.source) {
+      case 'read emails': {
+        ret = `email-pattern.png`;
+        break;
+      }
+      // Every way a stranger reaches us through a web surface reads as web: the
+      // chat widget, a contact form, and the older plain 'web'. They are the
+      // same story to whoever is looking at the card.
+      case 'web':
+      case 'widget':
+      case 'contact_form': {
+        ret = `web-pattern.png`;
+        break;
+      }
+      // A contact the phone system created for an unknown caller (voice_module
+      // writes this when an inbound call comes from a number we do not hold).
+      case 'inbound_call': {
+        ret = `phone-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;
 };
 
@@ -5421,6 +5621,16 @@ export const ts_contact = async function (uid, contact_id) {
 };
 
 const set_account_profile_picture = async function (uid, account_uid, metadata, job_id, headers, account_profile_info) {
+  // Normalised HERE rather than at each call site because every background
+  // trigger — verify_account, the L2 crossing, the widget signup — has no
+  // request to take headers from, and an omitted argument arrives as null over
+  // the queue rather than undefined, so a default parameter would not catch it.
+  // drive_module reads headers['cf-connecting-ip'] unguarded when it records an
+  // upload, so a null threw there and the whole generation was lost. It failed
+  // quietly: the throw was caught below and written to profile_avatar_error,
+  // which nothing displays, leaving accounts sitting at stat 1 with no avatar
+  // and no visible reason.
+  headers = headers || {};
   await update_account_profile_picture_status(account_uid, 1);
   try {
     let profile_picture;
@@ -5451,7 +5661,7 @@ const set_account_profile_picture = async function (uid, account_uid, metadata,
       profile_picture = account_info.profile_picture;
     }
 
-    if (!account_info.profile_avatar) {
+    if (avatar_is_due(account_info)) {
       let business_size;
 
       switch (account_obj.membership_plan) {
@@ -5499,6 +5709,28 @@ const set_account_profile_picture = async function (uid, account_uid, metadata,
       if (!_.isObject(file_ret.data)) throw new Error('file_ret not an object');
       account_info.profile_avatar_obj = file_ret.data;
       account_info.profile_avatar = account_info.profile_avatar_obj.file_url;
+      // Which photo this avatar was made from. Saved in the same write as the
+      // avatar so the two can never disagree, and read back by avatar_is_due —
+      // it is what stops a generation repeating and what makes the next photo
+      // change ask for a new one.
+      account_info.profile_avatar_from = account_info.profile_picture;
+      // WHICH of the two things ai_module produced. get_profile_avatar makes an
+      // 'authentic profile' — the person's own face, restored if needed,
+      // background removed, centred on the detected face box — when the photo
+      // can carry one, and silently falls back to a 'fictional' likeness
+      // generated from the account's metadata when it cannot.
+      //
+      // That distinction is the whole point of holding this behind level 2: the
+      // avatar is meant to BE the verified person, and an invented face
+      // presented as theirs would say something untrue about an account that
+      // has just proved who it belongs to. The picture window reads this and
+      // says so rather than letting the substitution pass unremarked.
+      //
+      // Nothing had ever written avatar_source on the ACCOUNT path, though the
+      // contact and profile builders set it and every card builder copies
+      // account_info.avatar_source onto the doc it makes — so they were all
+      // copying undefined.
+      account_info.avatar_source = file_ret.data.avatar_source;
 
       const account_save_ret = await db_module.save_couch_doc('xuda_accounts', account_obj);
       await update_account_profile_picture_status(account_uid, 3);
@@ -5511,12 +5743,18 @@ const set_account_profile_picture = async function (uid, account_uid, metadata,
   }
 };
 
-// Internal trigger used by the widget Google-signup flow: when a freshly-created
-// visitor account already has a profile_picture (their Google photo) but no
-// generated avatar yet, kick off avatar generation. set_account_profile_picture
-// maintains profile_avatar_stat (1 → 2 → 3); the caller polls that. Mirrors the
-// opportunistic trigger in update_account_info (profile_avatar_stat !== 2 guards
-// against re-triggering while a generation is mid-flight).
+// The one internal entry point for "start this account's avatar if one is
+// owed". Called by the widget Google-signup flow (a fresh visitor arriving with
+// their Google photo) and by verify_module the moment an account crosses into
+// level 2, which is the trigger that matters: reaching level 2 is what earns the
+// avatar, and it can be reached without anyone touching this account's profile.
+//
+// Every rule lives in the two helpers rather than here, so a caller cannot get
+// an avatar for an account that has not earned one by picking this door:
+// can_generate_avatar holds the level bar, avatar_is_due holds "not already
+// made from this photo, and not already running". A caller with nothing owing
+// is a cheap no-op. set_account_profile_picture maintains profile_avatar_stat
+// (1 → 2 → 3), which is what the dashboard polls.
 export const ensure_profile_avatar = async function (req, job_id, headers) {
   try {
     const { uid } = req || {};
@@ -5524,7 +5762,7 @@ export const ensure_profile_avatar = async function (req, job_id, headers) {
     const { code, data: account_obj } = await db_module.get_couch_doc('xuda_accounts', uid);
     if (code < 0 || !account_obj) return { code: -1, data: 'account not found' };
     const info = account_obj.account_info || {};
-    if (info.profile_picture && !info.profile_avatar && info.profile_avatar_stat !== 2) {
+    if (can_generate_avatar(account_obj) && avatar_is_due(info)) {
       // Best-effort profile context for AI-usage attribution. A freshly-created
       // widget visitor may have no profile/project yet — tolerate that.
       let account_profile_info;
@@ -6919,6 +7157,9 @@ export const archive_account_profile = async function (req) {
       await db_module.save_couch_doc('xuda_accounts', account_doc);
     }
 
+    // UI-202
+    log_profile_activity(uid, profile_id, 'archived', { by: 'user', reason: account_profile_doc.stat_reason }, app_id);
+
     return account_profile_save_ret;
   } catch (err) {
     return {
@@ -6952,6 +7193,10 @@ export const delete_account_profile = async function (req, job_id, headers) {
     }
 
     ai_msa.delete_depended_chats(uid, profile_id);
+
+    // UI-202: the last row this profile gets.
+    log_profile_activity(uid, profile_id, 'deleted', { by: 'user', reason: account_profile_doc.stat_reason, note: 'the chats that hung off this profile were deleted with it' }, app_id);
+
     return account_profile_save_ret;
   } catch (err) {
     return {
@@ -6979,6 +7224,9 @@ export const unarchive_account_profile = async function (req) {
 
       const account_profile_save_ret = await db_module.save_app_couch_doc(app_id, account_profile_doc);
 
+      // UI-202
+      log_profile_activity(uid, profile_id, 'unarchived', { by: 'user' }, app_id);
+
       return account_profile_save_ret;
     }
   } catch (err) {
@@ -7016,6 +7264,9 @@ export const create_account_profile = async function (req, job_id, headers) {
     const save_ret = await db_module.save_app_couch_doc(app_id, doc);
     // acc_obj.active_profile_id = save_ret.data.id;
 
+    // UI-202: the first row of this profile's trail.
+    log_profile_activity(uid, doc._id, 'created', { by: 'user', name: profile_name, type: account_type, main: !!main, mailbox: !!email_account_id }, app_id);
+
     // return { code: 55, data: save_ret };
     return save_ret;
   } catch (err) {
@@ -7052,12 +7303,17 @@ export const update_account_profile = async function (req, job_id, headers) {
     }
 
     let changes_arr = [];
+    // UI-202: the previous values of the fields this edit touches, so the trail can say what
+    // it changed FROM as well as to. Taken inside the same loop that detects the change, so
+    // it costs nothing and cannot drift from changes_arr.
+    const previous_values = {};
 
     for (const key of account_profile_properties) {
       let val = req[key];
       if (typeof val === 'undefined') continue;
       if (account_profile_doc[key] !== val) {
         changes_arr.push(key);
+        previous_values[key] = account_profile_doc[key];
         account_profile_doc[key] = val;
       }
     }
@@ -7071,6 +7327,27 @@ export const update_account_profile = async function (req, job_id, headers) {
 
     const save_ret = await db_module.save_app_couch_doc(app_id, account_profile_doc);
 
+    // UI-202: one row naming the fields that moved, with the values of the ones that read
+    // as values (a signature and an avatar url do not). Auto response gets its OWN row on
+    // top: it is the switch that decides whether this profile answers mail by itself, so
+    // "auto response" buried in a list of six field names is not good enough.
+    const changed = changes_arr.map((key) => PROFILE_FIELD_LABELS[key] || key.replace(/_/g, ' '));
+    const values = {};
+    for (const key of changes_arr) {
+      if (PROFILE_FIELDS_WITH_VALUES.has(key)) values[PROFILE_FIELD_LABELS[key] || key] = String(account_profile_doc[key] ?? '').slice(0, 120);
+    }
+    log_profile_activity(uid, _id, 'updated', { by: 'user', changed: [...new Set(changed)], values, previous_name: changes_arr.includes('profile_name') ? previous_values.profile_name : undefined }, app_id);
+
+    if (changes_arr.includes('auto_respond')) {
+      log_profile_activity(
+        uid,
+        _id,
+        account_profile_doc.auto_respond ? 'auto_respond_on' : 'auto_respond_off',
+        { by: 'user', mode: account_profile_doc.auto_respond_mode, agents: (account_profile_doc.auto_respond_agents || []).length },
+        app_id
+      );
+    }
+
     return { code: 56, data: save_ret };
   } catch (err) {
     return { code: -56, data: err.message };
@@ -7166,6 +7443,135 @@ const log_contact_activity = async function (uid, contact_id, event, detail = {}
   }
 };
 
+// ─── UI-202: the account profile activity trail ───────────────────────────────────────
+// The fourth of the same family (contacts UI-134, agents and chats UI-194/195), same shape
+// because one panel renders all of them. A profile doc keeps the current answer to every
+// question and nothing about when it changed, and a profile is the thing that answers mail
+// on its own: "when was auto respond switched on", "which agents were attached", "who
+// changed the signature" had no trace at all.
+//
+// Append-only, never awaited, and a failure to write it can never fail the action it
+// records. Lives in the same app db as the profile.
+const log_profile_activity = async function (uid, profile_id, event, detail = {}, app_id) {
+  try {
+    if (!uid || !profile_id || !event) return null;
+    const app = app_id || (await get_account_default_project_id(uid));
+    if (!app) return null;
+
+    return await db_module.save_app_couch_doc_native(app, {
+      _id: await _common.xuda_get_uuid('profile_activity'),
+      docType: 'profile_activity',
+      profile_id,
+      uid,
+      event,
+      detail,
+      ts: Date.now(),
+      stat: 3,
+    });
+  } catch (err) {
+    console.error('[account_module] profile activity not recorded:', event, profile_id, err?.message || err);
+    return null;
+  }
+};
+
+// The cross-module door: ai_module regenerates a profile's avatar, team_module shares one.
+export const log_account_profile_activity = async function (req) {
+  const { uid, profile_id, event, detail, app_id } = req || {};
+  const ret = await log_profile_activity(uid, profile_id, event, detail || {}, app_id);
+  return { code: ret ? 1 : 0, data: ret ? { profile_id, event } : 'not recorded' };
+};
+
+// Field names the edit row prints, and the ones whose VALUE is safe and useful to print
+// with them. A signature is free text and an avatar is a url, so those travel as the fact
+// that they changed; a name, a mode or a model is the whole point of the row.
+const PROFILE_FIELD_LABELS = {
+  profile_name: 'name',
+  profile_signature: 'signature',
+  email_account_id: 'mailbox',
+  profile_picture: 'picture',
+  profile_avatar: 'avatar',
+  profile_picture_obj: 'picture',
+  profile_avatar_obj: 'avatar',
+  auto_respond: 'auto response',
+  auto_respond_mode: 'auto response mode',
+  auto_respond_agents: 'auto response agents',
+  account_type: 'type',
+  active_ai_model: 'model',
+  ai_models: 'models',
+  active_agents: 'agents',
+  email_template: 'email template',
+};
+const PROFILE_FIELDS_WITH_VALUES = new Set(['profile_name', 'auto_respond_mode', 'account_type', 'active_ai_model']);
+
+export const get_account_profile_activity = async function (req) {
+  const { uid, profile_id } = req;
+  try {
+    if (!profile_id) throw new Error('profile_id is missing');
+    const app_id = await get_account_default_project_id(uid);
+
+    let profile_doc;
+    try {
+      profile_doc = await db_module.get_app_couch_doc_native(app_id, profile_id);
+    } catch (_) {
+      profile_doc = null;
+    }
+    if (!profile_doc || profile_doc.docType !== 'account_profile') throw new Error(`profile ${profile_id} not found`);
+    if (profile_doc.uid !== uid) throw new Error('Operation not allowed');
+
+    const recorded_ret = await db_module.find_app_couch_query(app_id, {
+      selector: { docType: 'profile_activity', profile_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;
+      if (recorded.some((r) => r.event === event)) return;
+      derived.push({ event, detail, ts, derived: true });
+    };
+
+    const created_ts = profile_doc.date_created_ts || profile_doc.ts;
+    add('created', created_ts, { name: profile_doc.profile_name, type: profile_doc.account_type, main: !!profile_doc.main });
+    if (profile_doc.email_account_id) add('mailbox_bound', profile_doc.ts || created_ts, {});
+    if (profile_doc.auto_respond) add('auto_respond_on', profile_doc.ts || created_ts, { mode: profile_doc.auto_respond_mode, agents: (profile_doc.auto_respond_agents || []).length });
+    if (profile_doc.profile_avatar) add('avatar_ready', profile_doc.profile_avatar_stat_ts || profile_doc.ts || created_ts, {});
+    // UI-204: the two public surfaces, reconstructed from the flags they are stored as, so a
+    // profile that has been taking messages from strangers for months says so today rather
+    // than only from the next time somebody toggles it.
+    if (profile_doc.widget_enabled) add('widget_on', profile_doc.ts || created_ts, {});
+    if (profile_doc.contact_form_enabled) add('contact_form_on', profile_doc.ts || created_ts, {});
+    if (profile_doc.shared_from_uid) add('shared_with_you', profile_doc.shared_ts || created_ts, { from_uid: profile_doc.shared_from_uid });
+    if (profile_doc.stat === 5) add('archived', profile_doc.stat_ts, { reason: profile_doc.stat_reason });
+    if (profile_doc.stat === 4) add('deleted', profile_doc.stat_ts, { reason: profile_doc.stat_reason });
+
+    const rows = [...recorded, ...derived].sort((a, b) => (b.ts || 0) - (a.ts || 0));
+
+    return {
+      code: 1,
+      data: {
+        profile_id,
+        current: {
+          name: profile_doc.profile_name || null,
+          stat: profile_doc.stat,
+          main: !!profile_doc.main,
+          type: profile_doc.account_type || null,
+          auto_respond: !!profile_doc.auto_respond,
+          auto_respond_mode: profile_doc.auto_respond_mode || null,
+          mailbox: !!profile_doc.email_account_id,
+          model: profile_doc.active_ai_model || null,
+          agents: (profile_doc.active_agents || []).length,
+          widget: !!profile_doc.widget_enabled,
+          contact_form: !!profile_doc.contact_form_enabled,
+        },
+        rows,
+      },
+    };
+  } catch (err) {
+    return { code: -25, data: err.message };
+  }
+};
+
 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);
@@ -7503,6 +7909,96 @@ const _current_credit_period = function (account_doc) {
 
 // Single source of truth for "how many credits does this account have left".
 // Everything that gates, meters or displays credits must go through here.
+// The membership plans SELL a monthly AI allowance, but the only thing that has
+// ever minted it into the ledger is the Stripe invoice.paid webhook
+// (stripe_module `_grant_period_credits_for_invoice`). Miss that webhook once
+// and there is no second chance: `archive_expire_ai_credits` retires the last
+// grant at its 30-day mark, the balance silently falls back to the free daily
+// drip, and the account is hard-blocked by the gate while the plans page and
+// `get_effective_entitlements` both still promise the full allowance.
+//
+// That is not hypothetical. A Team account on dev sat at 1,600 granted until
+// 2026-08-11 09:00 UTC, when the cron expired a grant written on 2026-07-12.
+// Nothing replaced it, so the account dropped to 31 credits (30 daily drips
+// plus a friendship bonus) against 219 already spent, and every AI call was
+// refused. The old safety net for this, add_ai_credits_to_active_accounts, is
+// commented out (see the call site above).
+//
+// So the allowance heals itself: a paid membership with no live membership
+// grant gets THIS period's allowance minted here. Minting twice is what would
+// actually cost money, so three independent guards stand in the way: a live
+// grant from any membership plan wins, the account carries a per-period marker,
+// and record_ai_credit refuses a duplicate (credited_uid, details) outright.
+// The grant carries period_end_ts, so the expiry cron leaves it alone until the
+// period it belongs to is genuinely over.
+const _membership_plan_of = function (account_doc) {
+  const plan = _conf.PLAN_OBJ?.[account_doc?.membership_plan];
+  if (!plan || plan.category !== 'membership') return null;
+  // The free tier's allowance is the daily drip, which already writes its own
+  // ledger docs. Minting on top of it would hand every free account a second
+  // month's worth.
+  if (!(Number(plan.price) > 0)) return null;
+  const credits = Number(plan.features?.ai_credits);
+  if (!Number.isFinite(credits) || credits <= 0) return null;
+  return { plan, credits };
+};
+
+const _self_heal_period_grant = async function (uid, doc, period, by_source) {
+  try {
+    if (doc?.stat !== 3) return 0;
+    // Past due is exactly when an allowance should NOT be minted: the webhook
+    // only ever granted on a PAID invoice.
+    if (doc?.account_billing_hold_status) return 0;
+
+    const found = _membership_plan_of(doc);
+    if (!found) return 0;
+
+    // A live grant from any membership plan means the normal path worked (or a
+    // downgrade left the old one running). Either way this period is covered,
+    // and a plan change must not be a way to mint a second allowance.
+    for (const [source, amount] of Object.entries(by_source || {})) {
+      if (!(amount > 0)) continue;
+      const p = _conf.PLAN_OBJ?.[source];
+      if (p && p.category === 'membership') return 0;
+    }
+
+    // Already healed this period. A grant retired mid-period (an expiry, a
+    // roll) must not come back, so this is checked before minting, not after.
+    if (Number(doc.credits_selfheal_period_ts) === period.start) return 0;
+
+    const day = new Date(period.start).toISOString().slice(0, 10);
+    const ret = await record_ai_credit('system', found.credits, found.plan.id, `plan allowance ${found.plan.id} ${day}`, uid, {
+      kind: CREDIT_KIND.PERIOD,
+      period_start_ts: period.start,
+      period_end_ts: period.end,
+    });
+    if (!(ret?.code > -1)) return 0;
+
+    // Fresh read for the write: the caller's copy of the account doc may be
+    // held across a long request, and this marker must not ride on top of
+    // whatever else it has since changed.
+    try {
+      const fresh = await db_module.get_couch_doc_native('xuda_accounts', uid);
+      if (fresh) {
+        fresh.credits_selfheal_period_ts = period.start;
+        await db_module.save_couch_doc('xuda_accounts', fresh);
+      }
+    } catch (e) {
+      // The marker is an optimisation, not the guard: record_ai_credit's own
+      // duplicate check still makes a second mint impossible.
+      console.error('[credit selfheal marker]', e?.message || e);
+    }
+    if (doc && typeof doc === 'object') doc.credits_selfheal_period_ts = period.start;
+
+    console.log(`[credit selfheal] ${uid} +${found.credits} (${found.plan.id}) for period starting ${day}`);
+    return found.credits;
+  } catch (err) {
+    // Never let this break a balance read: the gate calls it on every AI call.
+    console.error('[credit selfheal]', err?.message || err);
+    return 0;
+  }
+};
+
 export const get_credit_balance = async function (uid, account_doc) {
   const doc = account_doc || (await db_module.get_couch_doc_native('xuda_accounts', uid));
   const period = _current_credit_period(doc);
@@ -7523,6 +8019,15 @@ export const get_credit_balance = async function (uid, account_doc) {
     else period_grant += credits;
   }
 
+  // Mint this period's plan allowance if nothing else did (see above). Costs
+  // nothing on the hot path when there is a live grant: every guard but the
+  // last reads state that is already in hand.
+  const healed = await _self_heal_period_grant(uid, doc, period, by_source);
+  if (healed > 0) {
+    period_grant += healed;
+    by_source[doc.membership_plan] = (by_source[doc.membership_plan] || 0) + healed;
+  }
+
   const usage_ret = await get_account_ai_usage({ uid, ts_from: period.start, ts_to: Date.now() });
   const used = _usage_total(usage_ret?.data?.usage);
 
@@ -8401,6 +8906,41 @@ export const archive_expire_ai_credits = async function () {
   }
 };
 
+// Of the three ai_credit queries in this file, two were already indexed and one
+// was not:
+//
+//   record_ai_credit's duplicate check    { docType, credited_uid, details }
+//        -> idx_billing_credit_lookup, fine
+//   archive_expire_ai_credits             { docType, stat, date_created_ts: { $lt } }
+//        -> stat_docType_date_created_ts-json-index, fine
+//   roll_credit_period's grant retirement { docType, credited_uid, stat }, limit 9999
+//        -> _all_docs, i.e. a FULL SCAN of the whole ledger on every period roll
+//
+// master's xuda_billing holds ~27.5k docs, so that last one read all of them to
+// return one account's handful of grants, and Couch logged "No matching index
+// found ... the number of documents examined is high in proportion to the number
+// of results returned" every time.
+//
+// credited_uid leads because it is by far the most selective field; all three
+// clauses are equalities, so there is no range field to keep last.
+//
+// Not host-gated: xuda_billing is reachable wherever this module runs, and the PUT
+// no-ops once the design doc is already there (including when it arrived by
+// replication rather than from this node's own run).
+(async () => {
+  try {
+    const ret = await db_module.create_couch_index('xuda_billing', {
+      index: { fields: ['credited_uid', 'docType', 'stat'] },
+      name: 'idx_credit_uid_type_stat',
+      ddoc: 'idx_credit_uid_type_stat',
+      type: 'json',
+    });
+    if (ret?.error) console.error('[credits] xuda_billing credited_uid/docType/stat index create failed:', ret.error);
+  } catch (err) {
+    console.error('[credits] xuda_billing credited_uid/docType/stat index init failed:', err?.message || err);
+  }
+})();
+
 export const read_accounts_emails = async function () {
   const active_accounts = await db_module.find_couch_query('xuda_accounts', { selector: { stat: 3, docType: 'account' }, limit: 99999 });
   for await (let account_doc of active_accounts.docs) {

package/index_ms.mjs

@@ -493,6 +493,14 @@ export const get_contact = async function (...args) {
   return await broker.send_to_queue("get_contact", ...args);
 };
 
+export const log_account_profile_activity = async function (...args) {
+  return await broker.send_to_queue("log_account_profile_activity", ...args);
+};
+
+export const get_account_profile_activity = async function (...args) {
+  return await broker.send_to_queue("get_account_profile_activity", ...args);
+};
+
 export const save_contact = async function (...args) {
   return await broker.send_to_queue("save_contact", ...args);
 };

package/index_msa.mjs

@@ -493,6 +493,14 @@ export const get_contact =  function (...args) {
    broker.send_to_queue_async("get_contact", ...args);
 };
 
+export const log_account_profile_activity =  function (...args) {
+   broker.send_to_queue_async("log_account_profile_activity", ...args);
+};
+
+export const get_account_profile_activity =  function (...args) {
+   broker.send_to_queue_async("get_account_profile_activity", ...args);
+};
+
 export const save_contact =  function (...args) {
    broker.send_to_queue_async("save_contact", ...args);
 };

package/package.json

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