@xuda.io/account_module 1.2.2290 → 1.2.2291

package/index.mjs

@@ -2,9 +2,13 @@ import path from 'path';
 import fs from 'fs';
 import crypto from 'node:crypto';
 import _ from 'lodash';
-// import { exec } from 'child_process';
-// import util from 'util';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { createRequire } from 'module';
 import { parsePhoneNumber } from 'libphonenumber-js';
+
+const _execFileP = promisify(execFile);
+const _require = createRequire(import.meta.url);
 import { countryCodeEmoji } from 'country-code-emoji';
 
 const account_info_properties = [
@@ -514,6 +518,41 @@ export const get_effective_entitlements = function (account_doc) {
   return { ai_credits, drive_gb };
 };
 
+// Which website-builder image modes an account may use. SVG and stock are always
+// available; the two gpt-image modes (gen_low = img-1, gen_high = img-2) require a
+// paid membership AND a non-free workspace credit plan. Single source of truth for
+// both the builder gate (ai_module.generate_site_draft) and the UI selector, which
+// disables the locked modes and shows an "upgrade" prompt.
+export const _site_build_image_modes = function (account_doc) {
+  const paid = !!(account_doc?.membership_plan && account_doc.membership_plan !== 'free');
+  const ws = account_doc?.ai_workspace_plan;
+  const has_ws_credits = !!(paid && ws && ws !== 'free_ai_workspace' && _conf.PLAN_OBJ?.[ws]?.category === 'ai_workspace');
+  const gen_ok = paid && has_ws_credits;
+  return {
+    svg: true,
+    stock: true,
+    gen_low: gen_ok,
+    gen_high: gen_ok,
+    upgrade: !gen_ok,
+    reason: gen_ok
+      ? ''
+      : (!paid
+          ? 'AI image generation needs a paid website plan and a workspace credit plan. Upgrade to unlock it.'
+          : 'AI image generation needs a workspace credit plan. Add one to unlock it.'),
+  };
+};
+
+export const get_site_build_image_modes = async function (req) {
+  try {
+    const uid = req?.uid || req?.token_ret?.data?.uid;
+    if (!uid) return { code: -1, data: 'not authorized' };
+    const account_doc = await db_module.get_couch_doc_native('xuda_accounts', uid);
+    return { code: 1, data: _site_build_image_modes(account_doc) };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 export const increment_account_usage = async function (req) {
   const { uid } = req;
 
@@ -1082,7 +1121,7 @@ export const mark_account_reviewed = async function (req) {
 //   limit: number — cap on docs processed (canary backfill).
 //   app_id: string — backfill only this specific app.
 export const backfill_app_costs = async function (opts = {}) {
-  const { dry_run = false, limit = null, app_id = null } = opts || {};
+  const { dry_run = false, limit = null, app_id = null, created_anchor_ts = null } = opts || {};
 
   // compute_app_cost lives in deploy_module/cost.mjs. Imported via
   // the same cross-module path convention used elsewhere in this
@@ -1146,6 +1185,17 @@ export const backfill_app_costs = async function (opts = {}) {
             action = 'nothing-to-bill';
             reason = 'monthly_total = 0';
           } else {
+            // Anchor the ledger START. The default `created_ts = now` keeps
+            // pre-ledger hours unbilled — correct for a fresh legacy stamp. But a
+            // migration whose OLD billing already covered up to a cycle boundary
+            // should pass created_anchor_ts = that boundary (the cycle start), so
+            // the new ledger bills FROM there and there's no cycle_start ->
+            // migration_date gap. last_billed_ts stays `now`: the cron is
+            // forward-only from the stamp regardless.
+            if (Number.isFinite(created_anchor_ts) && created_anchor_ts > 0) {
+              cost.created_ts = created_anchor_ts;
+              cost.segment_from_ts = created_anchor_ts;
+            }
             if (doc.app_status_code === APP_STATUS_DELETED) {
               cost.terminated_ts = doc.app_status_data ? new Date(doc.app_status_data).getTime() : Date.now();
               action = 'terminated';
@@ -1177,6 +1227,118 @@ export const backfill_app_costs = async function (opts = {}) {
   return summary;
 };
 
+// Targeted correction for the backfill's "created_ts = now" anchor. When a
+// migrated account's OLD billing already covered up to the current cycle start,
+// anchoring the new ledger at the migration date leaves the cycle_start ->
+// migration_date window UNBILLED. This re-anchors the EARLIEST app_cost segment
+// of each of the account's billable apps back to `anchor_ts` (the cycle start /
+// last-charge date) so the full cycle bills.
+//
+//   - Shifts ONLY the earliest segment start (created_ts + segment_from_ts, or
+//     the first history segment's from_ts when the app was resized this cycle);
+//     later resize segments are untouched, so the resize timeline is preserved.
+//   - Idempotent: an app whose earliest start is already at/before anchor_ts is
+//     skipped, so re-running is a no-op.
+//   - dry_run defaults TRUE: it NEVER writes unless called with { dry_run: false }.
+//     Recommended flow: dry-run -> review per_doc billable_before/after ->
+//     { dry_run:false } -> confirm the dashboard summary -> flush_deployment_usage_to_stripe.
+//
+// opts:
+//   uid: string          — account whose apps to re-anchor (required).
+//   anchor_ts: number    — ms epoch to anchor to = the cycle start (required).
+//   dry_run: boolean     — default true; pass false to persist.
+//   app_id: string       — limit to one app.
+//   cycle_end_ts: number — optional; when given, logs before/after billable $ per app.
+export const rebase_app_cost_anchor = async function (opts = {}) {
+  const { uid, anchor_ts, app_id = null, cycle_end_ts = null } = opts || {};
+  const dry_run = opts.dry_run !== false; // SAFE default: writes only when explicitly dry_run:false
+  if (!uid) return { code: -1, data: 'uid required' };
+  if (!Number.isFinite(anchor_ts) || anchor_ts <= 0) return { code: -1, data: 'anchor_ts (ms epoch of the cycle start) required' };
+
+  // compute_cycle_billable_amount lets the dry-run show the $ delta per app.
+  let compute_cycle_billable_amount = null;
+  try {
+    const cost_mod = await import(`${module_path}/deploy_module/cost.mjs`);
+    compute_cycle_billable_amount = cost_mod.compute_cycle_billable_amount;
+  } catch (e) {
+    // best-effort; the re-anchor itself does not need it.
+  }
+
+  const apps_ret = await db_module.get_couch_view('xuda_master', 'user_apps', {
+    startkey: [uid, ''],
+    endkey: [uid, 'ZZZZZ'],
+    include_docs: true,
+  });
+
+  const summary = {
+    note: 'dry_run=true logs only; call with { dry_run:false } to persist',
+    dry_run,
+    uid,
+    anchor_ts,
+    anchor_iso: new Date(anchor_ts).toISOString(),
+    scanned: 0,
+    rebased: 0,
+    skipped: 0,
+    errors: [],
+    per_doc: [],
+  };
+
+  for (const row of apps_ret?.data?.rows || []) {
+    const doc = row.doc;
+    if (!doc || doc.docType !== 'app') continue;
+    if (app_id && doc._id !== app_id) continue;
+    const cost = doc.app_cost;
+    if (!cost || !cost.created_ts) continue;
+    summary.scanned++;
+
+    try {
+      const has_history = Array.isArray(cost.history) && cost.history.length > 0;
+      const first_from = has_history ? cost.history[0].from_ts || cost.created_ts : cost.created_ts;
+
+      // Idempotent: the earliest segment already reaches back to (or past) the
+      // anchor -> nothing to do.
+      if (cost.created_ts <= anchor_ts && first_from <= anchor_ts) {
+        summary.skipped++;
+        summary.per_doc.push({ _id: doc._id, app_name: doc.app_name, action: 'skipped', reason: 'already anchored', created_ts: cost.created_ts });
+        continue;
+      }
+
+      const created_before = cost.created_ts;
+      const billable_before = cycle_end_ts && compute_cycle_billable_amount ? compute_cycle_billable_amount(doc, anchor_ts, cycle_end_ts) : null;
+
+      // Re-anchor ONLY the earliest segment start.
+      if (cost.created_ts > anchor_ts) cost.created_ts = anchor_ts;
+      if (has_history) {
+        if ((cost.history[0].from_ts || 0) > anchor_ts) cost.history[0].from_ts = anchor_ts;
+      } else if (cost.segment_from_ts && cost.segment_from_ts > anchor_ts) {
+        cost.segment_from_ts = anchor_ts; // single segment: keep it consistent with created_ts
+      }
+
+      const billable_after = cycle_end_ts && compute_cycle_billable_amount ? compute_cycle_billable_amount(doc, anchor_ts, cycle_end_ts) : null;
+
+      if (!dry_run) {
+        doc.app_cost = cost;
+        await db_module.save_couch_doc('xuda_master', doc);
+      }
+
+      summary.rebased++;
+      summary.per_doc.push({
+        _id: doc._id,
+        app_name: doc.app_name,
+        app_type: doc.app_type,
+        action: dry_run ? 'would-rebase' : 'rebased',
+        created_ts_before: created_before,
+        created_ts_after: cost.created_ts,
+        ...(billable_before != null ? { billable_before: Number(billable_before.toFixed(2)), billable_after: Number(billable_after.toFixed(2)) } : {}),
+      });
+    } catch (err) {
+      summary.errors.push({ _id: doc._id, message: err.message });
+    }
+  }
+
+  return { code: 1, data: summary };
+};
+
 // True when a plan is team-tier or higher (team/agency/enterprise_*). Sponsoring a
 // login screen requires this tier both at invite time and while the sponsorship is served.
 export const is_login_sponsor_tier = function (membership_plan) {
@@ -2101,7 +2263,7 @@ export const ops_deploy_server = async function (req = {}) {
     const plan = { server_id, mode, current_state: _srv_deploy_state(doc), busy: _srv_busy(doc), private_ip: doc.private || null };
     if (req.dry_run) return { code: 1, data: { dry_run: true, would_deploy: plan } };
 
-    // Confirmation gate — proportional to blast radius.
+    // Confirmation gate, proportional to blast radius.
     if (mode === 'hard') {
       if (req.confirm !== server_id) return { code: -1, data: `hard deploy tears down and reinstalls "${server_id}" (brief downtime). Re-send with confirm:"${server_id}" to proceed.` };
     } else {
@@ -2167,6 +2329,325 @@ export const ops_server_deploy_status = async function (req = {}) {
   } catch (err) { return { code: -1, data: err.message }; }
 };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Ops: batch module hot-fix across selected region app-servers.
+//
+// utils/hotfix_prod.mjs is the surgical per-module patcher: it pulls the freshly
+// published @xuda.io npm versions onto each box and reloads ONLY the affected pm2
+// processes (no teardown, no config touch, unlike a full rollout). These methods
+// expose it to the ops Servers screen so a superuser can pick servers + modules
+// and run it as a batch instead of ssh'ing to a box. It runs on whatever fleet
+// node serves this request (regions carry utils/, npm auth and the WG key), and
+// --hosts is ALWAYS explicit so it targets exactly the selection regardless of
+// which node runs it. Dry-run (preview) writes nothing; apply is confirm-gated
+// and audited, the same discipline as ops_deploy_server.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _HOTFIX_TOOL = () => path.join(process.env.XUDA_HOME, 'utils', 'hotfix_prod.mjs');
+const _NPM_SCOPE = '@xuda.io';
+
+// Managed-module universe = config.json `modules` keys (what a full rollout
+// installs), the same set hotfix_prod manages.
+const _ops_module_universe = () => Object.keys((_conf && _conf.modules) || {}).sort();
+
+// module -> pm2 process name, derived from ecosystem.config.js exactly like
+// hotfix_prod.buildModuleProcMap: a broker app whose `args` is a bare
+// "<x>_module", or a script that runs a published module. Modules with no entry
+// are libraries (no own process; a version bump only lands when importers reload).
+let _ops_proc_map_cache = null;
+const _ops_proc_map = () => {
+  if (_ops_proc_map_cache) return _ops_proc_map_cache;
+  const map = {};
+  try {
+    const eco = _require(path.join(process.env.XUDA_HOME, 'ecosystem.config.js'));
+    for (const app of eco.apps || []) {
+      let mod = null;
+      if (typeof app.args === 'string' && /^[a-z0-9_]+_module$/.test(app.args.trim())) mod = app.args.trim();
+      else if (typeof app.script === 'string') { const m = app.script.match(/@xuda\.io\/([a-z0-9_]+_module)\//); if (m) mod = m[1]; }
+      if (mod) map[mod] = app.name;
+    }
+  } catch (e) {}
+  _ops_proc_map_cache = map;
+  return map;
+};
+
+// Bounded-concurrency map (npm view is per-package and slowish).
+const _ops_pool = async (items, n, fn) => {
+  const res = new Array(items.length);
+  let i = 0;
+  await Promise.all(Array.from({ length: Math.min(n, items.length || 1) }, async () => {
+    while (i < items.length) { const idx = i++; res[idx] = await fn(items[idx], idx); }
+  }));
+  return res;
+};
+
+// Latest published version + its publish date for one @xuda.io module (uses the
+// box's ~/.npmrc for private-registry auth, same as hotfix_prod).
+const _ops_npm_info = async (mod) => {
+  try {
+    const { stdout } = await _execFileP('npm', ['view', `${_NPM_SCOPE}/${mod}`, 'version', 'time', '--json'], { maxBuffer: 8 * 1024 * 1024, timeout: 20000 });
+    const j = JSON.parse(stdout || '{}');
+    const version = j.version || null;
+    const published_at = (version && j.time && j.time[version]) || (j.time && j.time.modified) || null;
+    return version ? { ok: true, version, published_at } : { ok: false, reason: 'no version' };
+  } catch (e) {
+    const t = String((e && (e.stderr || e.message)) || e);
+    if (/E404|404 Not Found|is not in this registry/i.test(t)) return { ok: false, reason: 'not published' };
+    if (/E403|403 Forbidden/i.test(t)) return { ok: false, reason: 'npm auth (403)' };
+    return { ok: false, reason: (t.split('\n')[0] || 'error').slice(0, 100) };
+  }
+};
+
+// Short cache: the module dropdown reopens often and npm view is slow.
+let _ops_modinfo_cache = { ts: 0, data: null };
+
+// Resolve selected server ids -> deployable region app-servers with a WG private
+// ip, as hotfix_prod --hosts targets (root@<private>). Rejects non-deployable /
+// dev / missing-ip with a reason, so the caller can surface exactly what dropped.
+const _ops_resolve_hotfix_hosts = async (server_ids) => {
+  const ids = [...new Set((server_ids || []).map((s) => String(s || '').trim()).filter(Boolean))];
+  if (!ids.length) return { ok: false, reason: 'select at least one server' };
+  const docs = await _load_all_server_docs();
+  const byId = {};
+  docs.forEach((d) => (byId[d._id] = d));
+  const hosts = [];
+  const rejected = [];
+  for (const id of ids) {
+    const d = byId[id];
+    if (!d) { rejected.push(`${id} (not found)`); continue; }
+    if (!_srv_is_deployable(d)) { rejected.push(`${id} (not a deployable region app-server)`); continue; }
+    const priv = d.private || (d.server_info && d.server_info.private_ip) || null;
+    if (!priv) { rejected.push(`${id} (no WireGuard private ip)`); continue; }
+    hosts.push({ id, ssh: `root@${priv}` });
+  }
+  return { ok: hosts.length > 0, hosts, rejected };
+};
+
+const _ops_validate_modules = (modules) => {
+  const universe = _ops_module_universe();
+  const list = [...new Set((modules || []).map((m) => String(m || '').trim()).filter(Boolean))];
+  return { list, unknown: list.filter((m) => !universe.includes(m)) };
+};
+
+// Spawn utils/hotfix_prod.mjs against explicit WG hosts. execFile rejects on a
+// non-zero exit (hotfix_prod exits 1 if ANY host failed), which we translate to
+// ok:false rather than throwing, keeping stdout for the summary either way.
+const _ops_run_hotfix = async ({ hosts, modules, dry_run, timeout_ms }) => {
+  const args = [_HOTFIX_TOOL(), '--hosts', hosts.map((h) => h.ssh).join(','), ...(modules || []), ...(dry_run ? ['--dry-run'] : [])];
+  try {
+    const { stdout, stderr } = await _execFileP('node', args, { maxBuffer: 32 * 1024 * 1024, timeout: timeout_ms || 300000, env: { ...process.env } });
+    return { ok: true, exit: 0, stdout: String(stdout || ''), stderr: String(stderr || '') };
+  } catch (e) {
+    return { ok: false, exit: e && typeof e.code === 'number' ? e.code : 1, stdout: String((e && e.stdout) || ''), stderr: String((e && (e.stderr || e.message)) || e) };
+  }
+};
+
+// Pull hotfix_prod's human summary block + a tail for the UI.
+const _ops_hotfix_summary = (stdout) => {
+  const lines = String(stdout || '').split('\n');
+  const i = lines.findIndex((l) => /######## summary ########/.test(l));
+  const summary = i >= 0 ? lines.slice(i + 1).map((l) => l.trim()).filter(Boolean).slice(0, 20) : [];
+  const tail = lines.map((l) => l.replace(/\s+$/, '')).filter((l) => l.trim()).slice(-40);
+  return { summary, tail };
+};
+
+// List the managed modules with their latest published version + publish date and
+// whether they have a reloadable pm2 process. Feeds the batch hot-fix module picker.
+export const ops_list_modules = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const universe = _ops_module_universe();
+    if (!universe.length) return { code: -1, data: 'no managed modules in config.modules' };
+    const proc = _ops_proc_map();
+    const now = Date.now();
+    if (!_ops_modinfo_cache.data || now - _ops_modinfo_cache.ts > 60000 || req.refresh) {
+      const infos = await _ops_pool(universe, 8, (m) => _ops_npm_info(m));
+      const byMod = {};
+      universe.forEach((m, i) => (byMod[m] = infos[i]));
+      _ops_modinfo_cache = { ts: now, data: byMod };
+    }
+    const info = _ops_modinfo_cache.data;
+    const modules = universe.map((name) => {
+      const ni = info[name] || {};
+      return {
+        name,
+        proc: proc[name] || null,
+        has_process: !!proc[name],
+        version: ni.ok ? ni.version : null,
+        published_at: ni.ok ? ni.published_at : null,
+        unavailable: ni.ok ? null : ni.reason || 'unresolved',
+      };
+    });
+    return { code: 1, data: { modules, count: modules.length, scope: _NPM_SCOPE, cached_ts: _ops_modinfo_cache.ts } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Preview a batch hot-fix: runs hotfix_prod --dry-run against the selected servers
+// (and optional module subset) and returns the plan. Writes NOTHING, so it needs
+// no confirmation and is safe to call from the confirm dialog's "Preview" button.
+export const ops_hotfix_preview = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const h = await _ops_resolve_hotfix_hosts(req.server_ids);
+    if (!h.ok) return { code: -1, data: `no deployable servers in the selection${h.rejected && h.rejected.length ? ': ' + h.rejected.join(', ') : ''}` };
+    const { list, unknown } = _ops_validate_modules(req.modules);
+    if (unknown.length) return { code: -1, data: `unknown module(s): ${unknown.join(', ')}` };
+    const run = await _ops_run_hotfix({ hosts: h.hosts, modules: list, dry_run: true, timeout_ms: 180000 });
+    const { summary, tail } = _ops_hotfix_summary(run.stdout);
+    return {
+      code: 1,
+      data: {
+        dry_run: true,
+        hosts: h.hosts.map((x) => x.id),
+        rejected: h.rejected || [],
+        modules: list.length ? list : 'all changed',
+        resolved: run.ok,
+        summary,
+        log_tail: tail,
+      },
+    };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// Apply a batch hot-fix to the selected region app-servers. JOB method (async,
+// long-running): the platform returns a job_id and the dashboard tracks progress.
+// Superuser + confirm:true gated (this reloads live prod processes); audited +
+// notified, the same discipline as ops_deploy_server. Idempotent per hotfix_prod:
+// modules already current on a box are skipped, so a re-run is safe.
+export const ops_batch_hotfix = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const h = await _ops_resolve_hotfix_hosts(req.server_ids);
+    if (!h.ok) return { code: -1, data: `no deployable servers in the selection${h.rejected && h.rejected.length ? ': ' + h.rejected.join(', ') : ''}` };
+    const { list, unknown } = _ops_validate_modules(req.modules);
+    if (unknown.length) return { code: -1, data: `unknown module(s): ${unknown.join(', ')}` };
+    if (req.confirm !== true && req.confirm !== 'true') {
+      return { code: -1, data: `this hot-fixes ${h.hosts.length} live server(s): ${h.hosts.map((x) => x.id).join(', ')}. Re-send with confirm:true to proceed.` };
+    }
+    const started = Date.now();
+    const mod_label = list.length ? list.join(', ') : 'all changed';
+    const run = await _ops_run_hotfix({ hosts: h.hosts, modules: list, dry_run: false, timeout_ms: 1200000 });
+    const { summary, tail } = _ops_hotfix_summary(run.stdout);
+    const host_ids = h.hosts.map((x) => x.id);
+    _ops_notify_ops(
+      `Batch hot-fix ${run.ok ? 'converged' : 'FAILED'}: ${host_ids.join(', ')}`,
+      [['Servers', host_ids.join(', ')], ['Modules', mod_label], ['By', req.uid], ['Result', run.ok ? 'converged' : `exit ${run.exit}`], ['Elapsed', Math.round((Date.now() - started) / 1000) + 's']],
+      'OPS-HOTFIX'
+    );
+    logs_msa.add_account_log({ uid: req.uid, method: 'ops_batch_hotfix', security: true, source: 'ops dashboard', response_status_code: run.ok ? 200 : 500, response_data: `hotfix [${mod_label}] on ${host_ids.join(',')} by ${req.uid}: ${run.ok ? 'converged' : 'FAILED exit ' + run.exit}` });
+    if (!run.ok) return { code: -1, data: { converged: false, hosts: host_ids, modules: list.length ? list : 'all changed', summary, log_tail: tail, error: (run.stderr || '').split('\n')[0] || `hotfix exit ${run.exit}` } };
+    return { code: 1, data: { converged: true, hosts: host_ids, modules: list.length ? list : 'all changed', summary, log_tail: tail, elapsed_ms: Date.now() - started } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
+// utils/regional_server_setup/index.mjs - the raw-box onboarding engine the supervisor
+// "Add infra box and region" button drives. Runs on the dev orchestrator (like the
+// publish rollout). The engine reads config.json + on-box secrets to get the fleet couch
+// admin + control-plane key.
+const _SETUP_TOOL = () => path.join(process.env.XUDA_HOME, 'utils', 'regional_server_setup', 'index.mjs');
+
+// The secrets file the engine merges over config.json. Prefer prod secrets; fall back to
+// the dev secrets (the fleet couch admin is shared). The box running this job must carry
+// one (the copy_secrets flow).
+const _ops_setup_secrets = () => {
+  for (const p of [process.env.XUDA_SECRETS, '/root/secrets.json', '/root/secrets_dev.json']) {
+    try { if (p && fs.existsSync(p)) return p; } catch (e) {}
+  }
+  return process.env.XUDA_SECRETS || '/root/secrets.json';
+};
+
+// Strip the ssh password from the spec before it is written to a temp file, logged, or
+// returned. The password ONLY ever travels as XUDA_SSH_PASS in the child env, is used for
+// the single first hop, and is never persisted to couch, a job doc, a log, or the audit.
+const _ops_setup_sanitize = (spec) => {
+  const s = JSON.parse(JSON.stringify(spec || {}));
+  if (s.ssh) { delete s.ssh.password; delete s.ssh.pass; }
+  delete s.ssh_password; delete s.password;
+  return s;
+};
+
+// Server-side spec validation (mirrors the engine's validate_spec) so the dialog gets a
+// clean error before anything is spawned.
+const _ops_setup_validate = (spec) => {
+  if (!spec || typeof spec !== 'object') return 'spec is required';
+  if (!Array.isArray(spec.targets) || !spec.targets.length) return 'targets must include "infra" and/or "region"';
+  for (const t of spec.targets) if (!['infra', 'region'].includes(t)) return `unknown target "${t}"`;
+  if (!spec.ssh || !spec.ssh.host) return 'ssh.host is required';
+  if (spec.targets.includes('infra') && (!spec.infra || !spec.infra.metro || !spec.infra.region)) return 'infra.metro + infra.region are required';
+  if (spec.targets.includes('region')) {
+    const c = Number(spec.region && spec.region.case);
+    if (![1, 2, 3].includes(c)) return 'region.case must be 1, 2, or 3';
+    if (!spec.region.code) return 'region.code is required';
+    if (!spec.region.source_region) return 'region.source_region is required';
+    if (c !== 1 && !spec.region.of_region) return 'region.of_region is required for a peer (case 2/3)';
+  }
+  return null;
+};
+
+// Spawn the engine against a temp spec file (password never in the file). Mirrors
+// _ops_run_hotfix: execFile rejects on a non-zero exit, translated to ok:false.
+const _ops_spawn_setup = async ({ spec, password, apply_fleet, dry_run, timeout_ms }) => {
+  const dir = path.join(process.env.XUDA_HOME, 'utils', 'temp');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch (e) {}
+  const spec_path = path.join(dir, `rss_${Date.now()}_${Math.floor(Math.random() * 1e6)}.json`);
+  fs.writeFileSync(spec_path, JSON.stringify(_ops_setup_sanitize(spec)), { mode: 0o600 });
+  const args = [_SETUP_TOOL(), spec_path, ...(dry_run ? ['--dry-run'] : []), ...(apply_fleet && !dry_run ? ['--apply-fleet'] : [])];
+  const env = { ...process.env, XUDA_SECRETS: _ops_setup_secrets() };
+  if (password && !dry_run) env.XUDA_SSH_PASS = String(password);
+  try {
+    const { stdout, stderr } = await _execFileP('node', args, { maxBuffer: 32 * 1024 * 1024, timeout: timeout_ms || 300000, env });
+    return { ok: true, exit: 0, stdout: String(stdout || ''), stderr: String(stderr || '') };
+  } catch (e) {
+    return { ok: false, exit: e && typeof e.code === 'number' ? e.code : 1, stdout: String((e && e.stdout) || ''), stderr: String((e && (e.stderr || e.message)) || e) };
+  } finally { try { fs.unlinkSync(spec_path); } catch (e) {} }
+};
+
+// Onboard a raw box (IP + user/pass) as an infra host, a region control-plane, or both.
+// JOB method (long-running). Superuser + confirm gated (this provisions a prod box + runs
+// the gated fleet writes); audited + notified with the password redacted. dry_run returns
+// the ordered plan and writes nothing. NOTE for the request layer: `ssh_password` is
+// transient and must be excluded from any request logging (the slim app_log does not
+// capture bodies; this method never persists it).
+export const ops_add_infra_box_region = async function (req = {}) {
+  try {
+    if (!_ops_is_super(req)) return { code: -403, data: 'superuser only' };
+    const spec = req.spec || {};
+    const verr = _ops_setup_validate(spec);
+    if (verr) return { code: -1, data: verr };
+    const password = req.ssh_password || (spec.ssh && (spec.ssh.password || spec.ssh.pass)) || '';
+    const label = `${(spec.targets || []).join('+')} on ${spec.ssh.host}`;
+
+    // Preview: run the engine --dry-run and return its ordered plan (writes nothing, so no
+    // confirm needed - safe from the dialog's Preview button).
+    if (req.dry_run) {
+      const run = await _ops_spawn_setup({ spec, dry_run: true, timeout_ms: 60000 });
+      const plan = String(run.stdout || run.stderr || '').split('\n').filter((l) => l.trim()).slice(-60);
+      return { code: 1, data: { dry_run: true, target: label, plan } };
+    }
+
+    if (!password) return { code: -1, data: 'ssh_password is required for the first hop (it is used once and never stored)' };
+    // install_pve reboots + reconfigures the host - a typed confirm, like ops_deploy_server hard mode.
+    const destructive = !!(spec.infra && spec.infra.install_pve !== false && (spec.targets || []).includes('infra'));
+    if (destructive) {
+      if (req.confirm !== spec.ssh.host) return { code: -1, data: `installing Proxmox on ${spec.ssh.host} reboots + reconfigures the host. Re-send with confirm:"${spec.ssh.host}" to proceed.` };
+    } else if (req.confirm !== true && req.confirm !== 'true') {
+      return { code: -1, data: `this provisions ${label} and applies the fleet writes. Re-send with confirm:true to proceed.` };
+    }
+
+    const started = Date.now();
+    const run = await _ops_spawn_setup({ spec, password, apply_fleet: true, dry_run: false, timeout_ms: 2400000 });
+    const tail = String(run.stdout || '').split('\n').map((l) => l.replace(/\s+$/, '')).filter((l) => l.trim()).slice(-50);
+    _ops_notify_ops(
+      `Add infra/region ${run.ok ? 'DONE' : 'FAILED'}: ${label}`,
+      [['Target', label], ['By', req.uid], ['Result', run.ok ? 'ok' : `exit ${run.exit}`], ['Elapsed', Math.round((Date.now() - started) / 1000) + 's']],
+      'OPS-ADD-BOX'
+    );
+    logs_msa.add_account_log({ uid: req.uid, method: 'ops_add_infra_box_region', security: true, source: 'ops dashboard', response_status_code: run.ok ? 200 : 500, response_data: `add box [${label}] by ${req.uid}: ${run.ok ? 'ok' : 'FAILED exit ' + run.exit}` });
+    if (!run.ok) return { code: -1, data: { ok: false, target: label, log_tail: tail, error: (run.stderr || '').split('\n')[0] || `engine exit ${run.exit}` } };
+    return { code: 1, data: { ok: true, target: label, log_tail: tail, elapsed_ms: Date.now() - started } };
+  } catch (err) { return { code: -1, data: err.message }; }
+};
+
 const TIPS_FILE_PATH = path.join(process.env.XUDA_HOME, 'dist', 'tips', 'tips.json');
 let _did_you_know_tips_cache = null;
 let _did_you_know_tips_cache_mtime = 0;
@@ -5951,6 +6432,435 @@ export const get_account_ai_usage = async function (req, job_id, headers) {
   }
 };
 
+/////////////////////////////////////////////////////////////////////////
+// CREDIT MANAGEMENT (Team plan): pool + per-profile / per-user / per-model /
+// per-source soft and hard limits, model allow/deny, freeze, threshold alerts.
+// Rules live on the owner account doc (xuda_accounts.<owner>.credit_rules) and
+// are evaluated centrally in evaluate_credit_gate. ai_module's
+// validate_credits_limit is a thin adapter that preserves the legacy
+// { credit_limit_error, account_id } Error contract, so absent or disabled
+// rules behave exactly as before (a single account-wide ledger cap).
+/////////////////////////////////////////////////////////////////////////
+
+// A limit is { type: 'credits' | 'percent', value: number }. percent is a share
+// of the granted pool (get_effective_entitlements().ai_credits) and is allowed on
+// pool / profile / user (allocation); model and source caps are absolute credits.
+const _resolve_limit = function (limit, entitlement) {
+  if (!limit || typeof limit.value !== 'number' || !(limit.value >= 0)) return Infinity;
+  if (limit.type === 'percent') {
+    if (!Number.isFinite(entitlement)) return Infinity; // unlimited pool: percent is uncapped
+    return entitlement * (limit.value / 100);
+  }
+  return limit.value;
+};
+
+// Team plan or above (rank compare, same basis as is_login_sponsor_tier).
+const _is_team_tier = function (membership_plan) {
+  const rank = _conf.PLAN_OBJ?.[membership_plan]?.rank;
+  const team_rank = _conf.PLAN_OBJ?.['team']?.rank;
+  if (typeof rank === 'number' && typeof team_rank === 'number') return rank >= team_rank;
+  return ['team', 'agency', 'enterprise_t1', 'enterprise_t2', 'enterprise_t3'].includes(membership_plan);
+};
+
+const _default_credit_rules = function () {
+  const d = _conf.credit_rules_defaults || {};
+  return {
+    version: 1,
+    enabled: false,
+    window: d.window || 'lifetime',
+    pool: {},
+    profiles: {},
+    users: {},
+    models: {},
+    sources: {},
+    alerts: { thresholds: Array.isArray(d.alert_thresholds) ? d.alert_thresholds : [80, 100], channels: ['ws', 'email'] },
+  };
+};
+
+// Fold the authoritative usage view ({ apid: { uid: credits } }) into per-profile
+// and per-user credit totals.
+const _fold_usage = function (profile_map) {
+  const by_profile = {};
+  const by_user = {};
+  for (const [apid, users] of Object.entries(profile_map || {})) {
+    for (const [u, amt] of Object.entries(users || {})) {
+      const n = Number(amt) || 0;
+      by_profile[apid] = (by_profile[apid] || 0) + n;
+      by_user[u] = (by_user[u] || 0) + n;
+    }
+  }
+  return { by_profile, by_user };
+};
+
+// Wide window so "used" reads as all-time spend (the lifetime / remaining-pool model).
+const _LIFETIME_WINDOW = { year_from: 2000, month_from: 1, day_from: 1, year_to: 2999, month_to: 12, day_to: 31 };
+
+// Per-model / per-source spend is not emitted by the usage view, so re-derive it
+// from the raw ai_usage docs and CALIBRATE to the view's authoritative total, so the
+// numbers stay in the same credit unit (factor = view_total / raw_token_cost_total).
+// Cached per owner (in-process, short TTL) so the hot gate path stays cheap.
+const _scoped_usage_cache = {};
+const _SCOPED_USAGE_TTL = 45000;
+const _get_scoped_usage = async function (owner_uid, need_raw) {
+  const now = Date.now();
+  const cached = _scoped_usage_cache[owner_uid];
+  if (cached && now - cached.ts < _SCOPED_USAGE_TTL && (!need_raw || cached.has_raw)) return cached.data;
+
+  const usage_ret = await get_account_ai_usage({ uid: owner_uid, ..._LIFETIME_WINDOW });
+  const total = Number(usage_ret?.data?.usage?.total) || 0;
+  const { by_profile, by_user } = _fold_usage(usage_ret?.data?.usage?.profile);
+
+  let by_model = {};
+  let by_source = {};
+  if (need_raw) {
+    try {
+      // ignore_warning=true: this selects on a nested field; add a Mango index on
+      // ['account_profile_info.uid'] before any prod rollout of per-model/source caps.
+      const raw = await db_module.find_couch_query(
+        'xuda_usage',
+        { selector: { docType: 'ai_usage', 'account_profile_info.uid': owner_uid }, fields: ['model', 'cost', 'input_tokens', 'output_tokens', 'source'], limit: 200000 },
+        true,
+      );
+      const raw_model = {};
+      const raw_source = {};
+      let raw_total = 0;
+      for (const doc of raw?.docs || []) {
+        const cost = doc.cost || { input: 1, output: 1 };
+        const c = ((Number(doc.input_tokens) || 0) * (Number(cost.input) || 0) + (Number(doc.output_tokens) || 0) * (Number(cost.output) || 0)) / 1e6;
+        raw_total += c;
+        const code = _conf.ai_model_aliases?.[doc.model] || doc.model || 'unknown';
+        raw_model[code] = (raw_model[code] || 0) + c;
+        const src = doc.source || 'other';
+        raw_source[src] = (raw_source[src] || 0) + c;
+      }
+      const factor = raw_total > 0 ? total / raw_total : 0;
+      for (const [k, v] of Object.entries(raw_model)) by_model[k] = Math.round(v * factor * 100) / 100;
+      for (const [k, v] of Object.entries(raw_source)) by_source[k] = Math.round(v * factor * 100) / 100;
+    } catch (e) {
+      console.error('[credit] scoped usage raw agg failed', e?.message || e);
+    }
+  }
+
+  const data = { total, credits_total: Number(usage_ret?.data?.credits?.total) || 0, by_profile, by_user, by_model, by_source };
+  _scoped_usage_cache[owner_uid] = { ts: now, has_raw: !!need_raw, data };
+  return data;
+};
+
+// Threshold alert (soft breach): debounced in-app WS event to owner (and the spender).
+const _soft_emit_timers = {};
+export const emit_credit_soft_limit = function (owner_uid, member_uid, scopes, channels) {
+  try {
+    if (!owner_uid || !Array.isArray(scopes) || !scopes.length) return;
+    if (Array.isArray(channels) && !channels.includes('ws')) return;
+    clearTimeout(_soft_emit_timers[owner_uid]);
+    _soft_emit_timers[owner_uid] = setTimeout(() => {
+      delete _soft_emit_timers[owner_uid];
+      try {
+        const to = [owner_uid];
+        if (member_uid && member_uid !== owner_uid) to.push(member_uid);
+        ws_dashboard_msa.emit_message_to_dashboard({ service: 'credit_soft_limit', to, data: { account_id: owner_uid, scopes, ts: Date.now() } });
+      } catch (e) {
+        console.error('[emit_credit_soft_limit]', e?.message || e);
+      }
+    }, 800);
+  } catch (e) {}
+};
+
+// Deduped (once per scope per day, in-process) owner email when a hard cap blocks.
+const _alert_email_sent = {};
+const _maybe_alert_email = function (owner_uid, scope, reason, channels) {
+  try {
+    if (!owner_uid || scope === 'model_access' || scope === 'freeze') return;
+    if (Array.isArray(channels) && !channels.includes('email')) return;
+    const day = Math.floor(Date.now() / 86400000);
+    const key = `${owner_uid}|${scope}|${day}`;
+    if (_alert_email_sent[key]) return;
+    _alert_email_sent[key] = true;
+    (async () => {
+      try {
+        const acc = await db_module.get_couch_doc_native('xuda_accounts', owner_uid);
+        const email = acc?.account_info?.email;
+        if (!email) return;
+        const body =
+          `<div style="font-family:Arial,Helvetica,sans-serif;font-size:15px;color:#111;line-height:1.5">` +
+          `<p>Heads up: an AI credit limit on your Xuda account was just reached.</p>` +
+          `<p>${_.escape(reason || 'A credit limit was reached.')}</p>` +
+          `<p>Open Credit Management in your dashboard to review your limits or top up.</p>` +
+          `</div>`;
+        email_msa.send_email({ email, subject: 'AI credit limit reached', body, display_type: 'info' });
+      } catch (e) {
+        console.error('[credit alert email]', e?.message || e);
+      }
+    })();
+  } catch (e) {}
+};
+
+const _model_access_blocks = function (ma, model_code) {
+  if (!ma || ma.mode === 'off' || !model_code) return false;
+  const allow = Array.isArray(ma.allow) ? ma.allow : [];
+  const deny = Array.isArray(ma.deny) ? ma.deny : [];
+  if (ma.mode === 'deny') return deny.includes(model_code);
+  if (ma.mode === 'allow') return allow.length > 0 && !allow.includes(model_code);
+  return false;
+};
+
+const _SCOPE_REASON = {
+  ledger: 'ai credits reach to hard limit',
+  pool: 'Your account has reached its AI credit limit.',
+  profile: 'This profile has reached its AI credit limit.',
+  user: 'This member has reached their AI credit limit.',
+  model: 'This model has reached its AI credit limit.',
+  source: 'This action has reached its AI credit limit.',
+};
+
+const _has_keys = (o) => !!o && typeof o === 'object' && Object.keys(o).length > 0;
+const _profile_has_sources = function (profiles) {
+  if (!profiles) return false;
+  for (const p of Object.values(profiles)) if (_has_keys(p?.sources)) return true;
+  return false;
+};
+
+const _block = function (owner, kind, reason, breach) {
+  return { block: true, scope: breach.scope, reason, hard_breached: [breach], soft_breached: [], account_id: owner, block_kind: kind };
+};
+
+// The single credit gate. Never throws; returns a plain verdict object.
+export const evaluate_credit_gate = async function (req) {
+  const { uid, profile_id, model, source } = req || {};
+  try {
+    const api = await get_active_account_profile_info(uid, profile_id);
+    const owner = api?.uid || uid;
+    const apid = api?.account_profile_id;
+    const member_uid = uid;
+    const model_code = _conf.ai_model_aliases?.[model] || model || null;
+
+    const account_doc = await db_module.get_couch_doc_native('xuda_accounts', owner);
+    const rules = account_doc?.credit_rules;
+
+    // Back-compat: no rules or disabled => legacy single ledger cap, byte-for-byte.
+    if (!rules || rules.enabled === false) {
+      const usage = await get_account_ai_usage({ uid: owner });
+      const over = (Number(usage?.data?.credits?.total) || 0) - (Number(usage?.data?.usage?.total) || 0) < -0.5;
+      return { block: over, scope: over ? 'pool' : null, reason: over ? _SCOPE_REASON.ledger : '', hard_breached: over ? [{ scope: 'pool', key: 'ledger' }] : [], soft_breached: [], account_id: owner };
+    }
+
+    // Freeze (hard stop, no usage lookup needed).
+    if (apid && rules.profiles?.[apid]?.frozen) return _block(owner, 'freeze', 'This profile is paused.', { scope: 'profile', key: apid, kind: 'frozen' });
+    if (member_uid && rules.users?.[member_uid]?.frozen) return _block(owner, 'freeze', 'This member is paused.', { scope: 'user', key: member_uid, kind: 'frozen' });
+
+    // Model access (allow/deny): profile rule then user rule.
+    if (_model_access_blocks(rules.profiles?.[apid]?.model_access, model_code)) return _block(owner, 'model_access', 'This model is not allowed for this profile.', { scope: 'model', key: model_code, kind: 'model_access' });
+    if (_model_access_blocks(rules.users?.[member_uid]?.model_access, model_code)) return _block(owner, 'model_access', 'This model is not allowed for this member.', { scope: 'model', key: model_code, kind: 'model_access' });
+
+    // Usage-based caps.
+    const entitlement = get_effective_entitlements(account_doc).ai_credits;
+    const need_raw = !!(_has_keys(rules.models) || _has_keys(rules.sources) || _profile_has_sources(rules.profiles));
+    const su = await _get_scoped_usage(owner, need_raw);
+
+    const hard = [];
+    const soft = [];
+    const consider = function (scope, key, rule, used) {
+      if (!rule) return;
+      const h = _resolve_limit(rule.hard, entitlement);
+      const s = _resolve_limit(rule.soft, entitlement);
+      if (used >= h) hard.push({ scope, key, limit: h, used, type: rule.hard?.type || 'credits' });
+      else if (used >= s) soft.push({ scope, key, limit: s, used, type: rule.soft?.type || 'credits', pct: s > 0 ? Math.round((used / s) * 100) : 100 });
+    };
+
+    // Pool: ledger safety (remaining below zero) plus the configured pool guardrail.
+    if (su.credits_total - su.total < -0.5) hard.push({ scope: 'pool', key: 'ledger' });
+    consider('pool', 'pool', rules.pool, su.total);
+    if (apid) consider('profile', apid, rules.profiles?.[apid], su.by_profile[apid] || 0);
+    if (member_uid) consider('user', member_uid, rules.users?.[member_uid], su.by_user[member_uid] || 0);
+    if (model_code) consider('model', model_code, rules.models?.[model_code], su.by_model[model_code] || 0);
+    if (source) {
+      consider('source', source, rules.sources?.[source], su.by_source[source] || 0);
+      if (apid) consider('source', `${apid}:${source}`, rules.profiles?.[apid]?.sources?.[source], su.by_source[source] || 0);
+    }
+
+    if (hard.length) {
+      const first = hard[0];
+      const reason = _SCOPE_REASON[first.key === 'ledger' ? 'ledger' : first.scope] || _SCOPE_REASON.pool;
+      _maybe_alert_email(owner, first.scope, reason, rules.alerts?.channels);
+      return { block: true, scope: first.scope, reason, hard_breached: hard, soft_breached: soft, account_id: owner };
+    }
+    if (soft.length) emit_credit_soft_limit(owner, member_uid, soft, rules.alerts?.channels);
+    return { block: false, scope: null, reason: '', hard_breached: [], soft_breached: soft, account_id: owner };
+  } catch (err) {
+    // Fail open: a rules bug must not block all AI usage. Logged for follow-up.
+    console.error('[evaluate_credit_gate]', err?.message || err);
+    return { block: false, scope: null, reason: '', hard_breached: [], soft_breached: [], account_id: uid, error: err?.message };
+  }
+};
+
+// Originals only (not shared copies) belonging to the owner.
+const _list_owner_profiles = async function (owner_uid, app_id) {
+  if (!app_id) return [];
+  try {
+    const ret = await db_module.find_app_couch_query(app_id, { selector: { docType: 'account_profile', uid: owner_uid, stat: 3 }, fields: ['_id', 'profile_name', 'share_item_id'], limit: 500 });
+    return (ret?.docs || []).filter((d) => !d.share_item_id).map((d) => ({ account_profile_id: d._id, profile_name: d.profile_name || 'Profile' }));
+  } catch (e) {
+    console.error('[credit] list profiles', e?.message || e);
+    return [];
+  }
+};
+
+// Owner plus every member their profiles are shared with, name-resolved.
+const _list_owner_members = async function (owner_uid, profiles) {
+  const uids = new Set([owner_uid]);
+  for (const p of profiles || []) {
+    try {
+      const members = await get_account_profile_group_member_uids(owner_uid, p.account_profile_id);
+      for (const m of members) uids.add(m);
+    } catch (e) {}
+  }
+  const out = [];
+  for (const u of uids) {
+    try {
+      const acc = await db_module.get_couch_doc_native('xuda_accounts', u);
+      const ai = acc?.account_info || {};
+      const name = ai.account_type === 'business' ? ai.business_name || 'Member' : `${ai.first_name || ''} ${ai.last_name || ''}`.trim() || ai.email || 'Member';
+      out.push({ uid: u, name });
+    } catch (e) {
+      out.push({ uid: u, name: 'Member' });
+    }
+  }
+  return out;
+};
+
+// Combined read powering the Credit Management page and the profile-settings embed.
+export const get_credit_management = async function (req) {
+  try {
+    const uid = req?.uid || req?.token_ret?.data?.uid;
+    if (!uid) return { code: -1, data: 'not authorized' };
+    const account_doc = await db_module.get_couch_doc_native('xuda_accounts', uid);
+    const plan = account_doc?.membership_plan || 'free';
+    const can_edit = _is_team_tier(plan);
+    const rules = account_doc?.credit_rules || _default_credit_rules();
+    const ent = get_effective_entitlements(account_doc);
+    const unlimited = !Number.isFinite(ent.ai_credits);
+    const entitlements = { ai_credits: unlimited ? null : ent.ai_credits, unlimited };
+
+    const su = await _get_scoped_usage(uid, true);
+    const remaining = unlimited ? null : Math.round((ent.ai_credits - su.total) * 100) / 100;
+    const usage_breakdown = {
+      window: { mode: rules.window || 'lifetime' },
+      pool: { used: Math.round(su.total * 100) / 100, remaining },
+      by_profile: su.by_profile,
+      by_user: su.by_user,
+      by_model: su.by_model,
+      by_source: su.by_source,
+    };
+
+    const model_catalog = {};
+    for (const [code, e] of Object.entries(_conf.ai_models || {})) {
+      model_catalog[code] = { name: e.name, type: e.type, price: e.price, model: e.model };
+    }
+
+    const app_id = account_doc?.account_project_id;
+    const profiles = await _list_owner_profiles(uid, app_id);
+    const members = await _list_owner_members(uid, profiles);
+
+    return { code: 1, data: { rules, can_edit, plan, entitlements, usage_breakdown, model_catalog, profiles, members } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
+const _normalize_limit = function (l, allow_percent) {
+  if (!l || typeof l !== 'object') return undefined;
+  const value = Number(l.value);
+  if (!(value >= 0)) return undefined;
+  const type = allow_percent && l.type === 'percent' ? 'percent' : 'credits';
+  const out = { type, value };
+  if (type === 'percent' && value > 100) out.value = 100;
+  return out;
+};
+const _normalize_softhard = function (obj, allow_percent) {
+  const out = {};
+  const s = _normalize_limit(obj?.soft, allow_percent);
+  const h = _normalize_limit(obj?.hard, allow_percent);
+  if (s) out.soft = s;
+  if (h) out.hard = h;
+  return out;
+};
+const _normalize_model_access = function (m) {
+  const mode = ['off', 'allow', 'deny'].includes(m?.mode) ? m.mode : 'off';
+  const codes = _conf.ai_models || {};
+  const clean = (arr) => (Array.isArray(arr) ? arr.filter((c) => typeof c === 'string' && codes[c]) : []);
+  return { mode, allow: clean(m?.allow), deny: clean(m?.deny) };
+};
+const _normalize_sources = function (src) {
+  const out = {};
+  if (src && typeof src === 'object') {
+    for (const [k, v] of Object.entries(src)) {
+      const sh = _normalize_softhard(v, false);
+      if (sh.soft || sh.hard) out[k] = sh;
+    }
+  }
+  return out;
+};
+const _normalize_credit_rules = function (input, uid) {
+  const d = _default_credit_rules();
+  const r = input && typeof input === 'object' ? input : {};
+  const out = {
+    version: 1,
+    enabled: r.enabled !== false,
+    window: r.window === 'monthly' ? 'monthly' : 'lifetime',
+    pool: _normalize_softhard(r.pool, true),
+    profiles: {},
+    users: {},
+    models: {},
+    sources: _normalize_sources(r.sources),
+    alerts: {
+      thresholds: Array.isArray(r.alerts?.thresholds) ? r.alerts.thresholds.map(Number).filter((n) => n > 0 && n <= 100) : d.alerts.thresholds,
+      channels: Array.isArray(r.alerts?.channels) ? r.alerts.channels.filter((c) => ['ws', 'email'].includes(c)) : ['ws', 'email'],
+    },
+    updated_ts: Date.now(),
+    updated_by: uid,
+  };
+  if (r.profiles && typeof r.profiles === 'object') {
+    for (const [apid, pv] of Object.entries(r.profiles)) {
+      out.profiles[apid] = { ..._normalize_softhard(pv, true), frozen: !!pv?.frozen, model_access: _normalize_model_access(pv?.model_access), sources: _normalize_sources(pv?.sources) };
+    }
+  }
+  if (r.users && typeof r.users === 'object') {
+    for (const [u, uv] of Object.entries(r.users)) {
+      out.users[u] = { ..._normalize_softhard(uv, true), frozen: !!uv?.frozen, model_access: _normalize_model_access(uv?.model_access) };
+    }
+  }
+  if (r.models && typeof r.models === 'object') {
+    const codes = _conf.ai_models || {};
+    for (const [code, mv] of Object.entries(r.models)) {
+      if (!codes[code]) continue;
+      const sh = _normalize_softhard(mv, false);
+      if (sh.soft || sh.hard) out.models[code] = sh;
+    }
+  }
+  return out;
+};
+
+// Save the credit rules on the owner account doc. Team plan only (also gated by
+// the cpi min_plan). A member saving here writes to their own account and never
+// touches the owner's pool, so "owner authors" falls out of the data model.
+export const set_credit_rules = async function (req) {
+  try {
+    const uid = req?.uid || req?.token_ret?.data?.uid;
+    if (!uid) return { code: -1, data: 'not authorized' };
+    const acc_ret = await db_module.get_couch_doc('xuda_accounts', uid, true); // fresh read for the write
+    if (acc_ret.code < 0) return acc_ret;
+    const account_doc = acc_ret.data;
+    if (!_is_team_tier(account_doc?.membership_plan)) return { code: -1, data: 'Credit management is available on the Team plan.' };
+    account_doc.credit_rules = _normalize_credit_rules(req.rules, uid);
+    await db_module.save_couch_doc('xuda_accounts', account_doc);
+    delete _scoped_usage_cache[uid];
+    broadcast_credits(uid);
+    return { code: 1, data: { rules: account_doc.credit_rules } };
+  } catch (err) {
+    return { code: -1, data: err.message };
+  }
+};
+
 export const get_account_ai_usage_old = async function (req, job_id, headers) {
   const { uid, year_from, month_from, day_from, year_to, month_to, day_to } = req;
   try {

package/index_ms.mjs

@@ -57,6 +57,14 @@ export const get_effective_entitlements = async function (...args) {
   return await broker.send_to_queue("get_effective_entitlements", ...args);
 };
 
+export const _site_build_image_modes = async function (...args) {
+  return await broker.send_to_queue("_site_build_image_modes", ...args);
+};
+
+export const get_site_build_image_modes = async function (...args) {
+  return await broker.send_to_queue("get_site_build_image_modes", ...args);
+};
+
 export const increment_account_usage = async function (...args) {
   return await broker.send_to_queue("increment_account_usage", ...args);
 };
@@ -81,6 +89,10 @@ export const backfill_app_costs = async function (...args) {
   return await broker.send_to_queue("backfill_app_costs", ...args);
 };
 
+export const rebase_app_cost_anchor = async function (...args) {
+  return await broker.send_to_queue("rebase_app_cost_anchor", ...args);
+};
+
 export const is_login_sponsor_tier = async function (...args) {
   return await broker.send_to_queue("is_login_sponsor_tier", ...args);
 };
@@ -201,6 +213,22 @@ export const ops_server_deploy_status = async function (...args) {
   return await broker.send_to_queue("ops_server_deploy_status", ...args);
 };
 
+export const ops_list_modules = async function (...args) {
+  return await broker.send_to_queue("ops_list_modules", ...args);
+};
+
+export const ops_hotfix_preview = async function (...args) {
+  return await broker.send_to_queue("ops_hotfix_preview", ...args);
+};
+
+export const ops_batch_hotfix = async function (...args) {
+  return await broker.send_to_queue("ops_batch_hotfix", ...args);
+};
+
+export const ops_add_infra_box_region = async function (...args) {
+  return await broker.send_to_queue("ops_add_infra_box_region", ...args);
+};
+
 export const did_you_know_tips = async function (...args) {
   return await broker.send_to_queue("did_you_know_tips", ...args);
 };
@@ -477,6 +505,22 @@ export const get_account_ai_usage = async function (...args) {
   return await broker.send_to_queue("get_account_ai_usage", ...args);
 };
 
+export const emit_credit_soft_limit = async function (...args) {
+  return await broker.send_to_queue("emit_credit_soft_limit", ...args);
+};
+
+export const evaluate_credit_gate = async function (...args) {
+  return await broker.send_to_queue("evaluate_credit_gate", ...args);
+};
+
+export const get_credit_management = async function (...args) {
+  return await broker.send_to_queue("get_credit_management", ...args);
+};
+
+export const set_credit_rules = async function (...args) {
+  return await broker.send_to_queue("set_credit_rules", ...args);
+};
+
 export const get_account_ai_usage_old = async function (...args) {
   return await broker.send_to_queue("get_account_ai_usage_old", ...args);
 };

package/index_msa.mjs

@@ -57,6 +57,14 @@ export const get_effective_entitlements =  function (...args) {
    broker.send_to_queue_async("get_effective_entitlements", ...args);
 };
 
+export const _site_build_image_modes =  function (...args) {
+   broker.send_to_queue_async("_site_build_image_modes", ...args);
+};
+
+export const get_site_build_image_modes =  function (...args) {
+   broker.send_to_queue_async("get_site_build_image_modes", ...args);
+};
+
 export const increment_account_usage =  function (...args) {
    broker.send_to_queue_async("increment_account_usage", ...args);
 };
@@ -81,6 +89,10 @@ export const backfill_app_costs =  function (...args) {
    broker.send_to_queue_async("backfill_app_costs", ...args);
 };
 
+export const rebase_app_cost_anchor =  function (...args) {
+   broker.send_to_queue_async("rebase_app_cost_anchor", ...args);
+};
+
 export const is_login_sponsor_tier =  function (...args) {
    broker.send_to_queue_async("is_login_sponsor_tier", ...args);
 };
@@ -201,6 +213,22 @@ export const ops_server_deploy_status =  function (...args) {
    broker.send_to_queue_async("ops_server_deploy_status", ...args);
 };
 
+export const ops_list_modules =  function (...args) {
+   broker.send_to_queue_async("ops_list_modules", ...args);
+};
+
+export const ops_hotfix_preview =  function (...args) {
+   broker.send_to_queue_async("ops_hotfix_preview", ...args);
+};
+
+export const ops_batch_hotfix =  function (...args) {
+   broker.send_to_queue_async("ops_batch_hotfix", ...args);
+};
+
+export const ops_add_infra_box_region =  function (...args) {
+   broker.send_to_queue_async("ops_add_infra_box_region", ...args);
+};
+
 export const did_you_know_tips =  function (...args) {
    broker.send_to_queue_async("did_you_know_tips", ...args);
 };
@@ -477,6 +505,22 @@ export const get_account_ai_usage =  function (...args) {
    broker.send_to_queue_async("get_account_ai_usage", ...args);
 };
 
+export const emit_credit_soft_limit =  function (...args) {
+   broker.send_to_queue_async("emit_credit_soft_limit", ...args);
+};
+
+export const evaluate_credit_gate =  function (...args) {
+   broker.send_to_queue_async("evaluate_credit_gate", ...args);
+};
+
+export const get_credit_management =  function (...args) {
+   broker.send_to_queue_async("get_credit_management", ...args);
+};
+
+export const set_credit_rules =  function (...args) {
+   broker.send_to_queue_async("set_credit_rules", ...args);
+};
+
 export const get_account_ai_usage_old =  function (...args) {
    broker.send_to_queue_async("get_account_ai_usage_old", ...args);
 };

package/package.json

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