@xuda.io/account_module 1.2.2312 → 1.2.2313

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
@@ -3410,6 +3474,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 +3546,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 +3781,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 +4448,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 +4483,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 +5588,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 +5628,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 +5676,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 +5710,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 +5729,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;
@@ -7503,6 +7708,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 +7818,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 +8705,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/package.json

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