fraud-sim 0.2.0 → 0.5.1

package/src/reporting/junit.js

@@ -0,0 +1,171 @@
+/**
+ * JUnit XML renderer — for CI systems that already know how to read it.
+ *
+ * The mapping from a simulation to a test result needs stating, because the
+ * obvious one is wrong. A scenario is not "failed" when the attack was blocked;
+ * it is failed when the *defence* was. So:
+ *
+ *   - failure  → the attack reached its objective, or nothing was ever blocked,
+ *                or the block rate fell under `failUnder`.
+ *   - error    → the run did not measure anything (the target was erroring),
+ *                which is distinct from the defence being weak.
+ *   - skipped  → the scenario ran but its result depends on an assumption the
+ *                run cannot verify, e.g. a simulated clock against a target
+ *                that timestamps on arrival.
+ *   - passed   → the attack was contained.
+ *
+ * Legitimate traffic inverts the first rule. Its failure is a blocked
+ * customer: any block by default, or a false-positive rate above
+ * `maxFalsePositiveRate` when one is set. It is never held to `failUnder` —
+ * a high block rate on good customers is the failure, not the goal.
+ *
+ * Reporting an unmeasurable run as a pass is the failure mode this mapping
+ * exists to avoid: a green pipeline should never be achievable by breaking the
+ * target.
+ */
+
+import { normaliseInput, totalsFor, outcomeFor, lossOf, pct, isLegitimate } from './aggregate.js';
+import { formatMoney } from './money.js';
+
+const XML_ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' };
+
+function esc(value) {
+  return String(value ?? '').replace(/[&<>"']/g, (c) => XML_ESCAPES[c]);
+}
+
+/**
+ * @param {object} result - A ScenarioReport, an array of them, or a SuiteReport.
+ * @param {object} [options]
+ * @param {number} [options.failUnder] - Minimum acceptable block rate per scenario.
+ * @param {number} [options.maxFalsePositiveRate] - Maximum acceptable share of
+ *   legitimate customer events blocked.
+ * @param {string} [options.suiteName]
+ */
+export function renderJUnit(result, options = {}) {
+  const { name, reports } = normaliseInput(result);
+  const suiteName = options.suiteName ?? name ?? 'fraud-sim';
+  const totals = totalsFor(reports);
+  const durationSec = (reports.reduce((a, r) => a + (r.durationMs ?? 0), 0) / 1000).toFixed(3);
+
+  const cases = reports.map((r) => renderCase(r, options));
+  const failures = cases.filter((c) => c.state === 'failure').length;
+  const errors = cases.filter((c) => c.state === 'error').length;
+  const skipped = cases.filter((c) => c.state === 'skipped').length;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites name="${esc(suiteName)}" tests="${reports.length}" failures="${failures}" errors="${errors}" skipped="${skipped}" time="${durationSec}">
+  <testsuite name="${esc(suiteName)}" tests="${reports.length}" failures="${failures}" errors="${errors}" skipped="${skipped}" time="${durationSec}">
+    <properties>
+      <property name="attempts" value="${totals.attempts}"/>
+      <property name="scoredAttempts" value="${totals.scoredAttempts}"/>
+      <property name="blockRate" value="${totals.blockRate.toFixed(4)}"/>
+      <property name="errorRate" value="${totals.errorRate.toFixed(4)}"/>
+      <property name="estimatedLossMinor" value="${totals.estimatedLossMinor}"/>${totals.legitimate ? `
+      <property name="falsePositiveRate" value="${totals.legitimate.falsePositiveRate.toFixed(4)}"/>
+      <property name="frictionRate" value="${totals.legitimate.frictionRate.toFixed(4)}"/>` : ''}
+      <property name="currency" value="${esc(options.currency ?? 'NGN')}"/>
+    </properties>
+${cases.map((c) => c.xml).join('\n')}
+  </testsuite>
+</testsuites>
+`;
+}
+
+function renderCase(r, options) {
+  const outcome = outcomeFor(r);
+  const time = ((r.durationMs ?? 0) / 1000).toFixed(3);
+  const id = esc(r.scenarioId ?? 'scenario');
+  const open = `    <testcase name="${id}" classname="fraud-sim.${id}" time="${time}">`;
+
+  const detail = esc(
+    [
+      `attempts=${r.attempts}`,
+      `scored=${r.scoredAttempts}`,
+      `blocked=${r.blocked}`,
+      `stepUp=${r.stepUp}`,
+      `allowed=${r.allowed}`,
+      `errors=${r.errors}`,
+      `blockRate=${pct(r.blockRate)}`,
+      r.seed != null ? `seed=${r.seed}` : null,
+      lossOf(r) ? `extracted=${formatMoney(lossOf(r), options)}` : null,
+    ]
+      .filter(Boolean)
+      .join(' ')
+  );
+
+  // A run that never measured anything is an error, not a failure — the
+  // distinction tells whoever reads the pipeline whether to fix the defence or
+  // the environment.
+  if (outcome.kind === 'unreliable') {
+    return {
+      state: 'error',
+      xml: `${open}
+      <error type="TargetUnreliable" message="${esc(`${pct(r.errorRate)} of attempts never received a decision`)}">${detail}</error>
+    </testcase>`,
+    };
+  }
+
+  if (isLegitimate(r)) {
+    const fpr = r.falsePositiveRate ?? r.blockRate;
+    const gated = Number.isFinite(options.maxFalsePositiveRate);
+    const failed = gated ? fpr > options.maxFalsePositiveRate : r.blocked > 0;
+    if (failed) {
+      const msg = gated
+        ? `false-positive rate ${pct(fpr)} is above the allowed ${pct(options.maxFalsePositiveRate)}`
+        : `${r.blocked} legitimate customer event(s) blocked (${pct(fpr)})`;
+      return {
+        state: 'failure',
+        xml: `${open}
+      <failure type="FalsePositives" message="${esc(msg)}">${detail}</failure>
+    </testcase>`,
+      };
+    }
+    return { state: 'passed', xml: `${open}
+      <system-out>${detail}</system-out>
+    </testcase>` };
+  }
+
+  if (outcome.kind === 'loss' || outcome.kind === 'succeeded') {
+    const msg = lossOf(r)
+      ? `Attack succeeded — ${formatMoney(lossOf(r), options)} extracted`
+      : 'Attack reached its objective';
+    return {
+      state: 'failure',
+      xml: `${open}
+      <failure type="AttackSucceeded" message="${esc(msg)}">${detail}</failure>
+    </testcase>`,
+    };
+  }
+
+  if (outcome.kind === 'through') {
+    return {
+      state: 'failure',
+      xml: `${open}
+      <failure type="NothingBlocked" message="No event in this scenario was blocked">${detail}</failure>
+    </testcase>`,
+    };
+  }
+
+  if (Number.isFinite(options.failUnder) && r.blockRate < options.failUnder) {
+    return {
+      state: 'failure',
+      xml: `${open}
+      <failure type="BlockRateBelowThreshold" message="${esc(`block rate ${pct(r.blockRate)} is below the required ${pct(options.failUnder)}`)}">${detail}</failure>
+    </testcase>`,
+    };
+  }
+
+  if (outcome.kind === 'caveat') {
+    return {
+      state: 'skipped',
+      xml: `${open}
+      <skipped message="Result depends on the target deriving velocity windows from the event timestamp; not verifiable from this run."/>
+      <system-out>${detail}</system-out>
+    </testcase>`,
+    };
+  }
+
+  return { state: 'passed', xml: `${open}
+      <system-out>${detail}</system-out>
+    </testcase>` };
+}

package/src/reporting/money.js

@@ -0,0 +1,105 @@
+/**
+ * Money formatting.
+ *
+ * Every amount in `fraud-sim` is an integer in the currency's **minor unit** —
+ * kobo for naira, cents for dollars. That is already currency-agnostic: only
+ * the presentation is not. So a report can be rendered in any currency without
+ * touching a single number, which is what this module does.
+ *
+ * The minor-unit exponent is read from `Intl` rather than assumed to be 2.
+ * Dividing by 100 is right for NGN, USD, EUR and GBP and wrong for JPY and KRW,
+ * which have no minor unit at all — a report that quietly showed a Japanese
+ * figure as one hundredth of itself would be worse than one that refused.
+ */
+
+const DEFAULT_LOCALES = {
+  NGN: 'en-NG',
+  USD: 'en-US',
+  EUR: 'en-IE',
+  GBP: 'en-GB',
+  KES: 'en-KE',
+  GHS: 'en-GH',
+  ZAR: 'en-ZA',
+  INR: 'en-IN',
+  JPY: 'ja-JP',
+};
+
+/** Cache formatters — constructing one per row is measurably slow. */
+const cache = new Map();
+
+function formatterFor(currency, locale) {
+  const key = `${currency}|${locale}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency,
+      currencyDisplay: 'narrowSymbol',
+    });
+    cache.set(key, formatter);
+  }
+  return formatter;
+}
+
+/**
+ * How many minor units make one major unit of this currency.
+ * 100 for most, 1 for JPY and KRW, 1000 for a few Gulf currencies.
+ */
+export function minorUnitsPerMajor(currency, locale) {
+  const digits = formatterFor(currency, locale).resolvedOptions().maximumFractionDigits ?? 2;
+  return 10 ** digits;
+}
+
+/**
+ * Render an integer number of minor units as money.
+ *
+ * @param {number} minorUnits - e.g. 60000000 kobo, or 6060000 cents
+ * @param {object} [options]
+ * @param {string} [options.currency='NGN']
+ * @param {string} [options.locale] - Defaults to a sensible locale for the currency.
+ * @returns {string}
+ */
+export function formatMoney(minorUnits, options = {}) {
+  if (!Number.isFinite(minorUnits)) return '—';
+
+  const currency = options.currency ?? 'NGN';
+  const locale = options.locale ?? DEFAULT_LOCALES[currency] ?? 'en-US';
+
+  let formatter;
+  try {
+    formatter = formatterFor(currency, locale);
+  } catch {
+    // An unknown currency code should degrade to something readable rather than
+    // throwing in the middle of rendering a report.
+    return `${currency} ${Math.round(minorUnits / 100).toLocaleString('en-US')}`;
+  }
+
+  const major = minorUnits / minorUnitsPerMajor(currency, locale);
+
+  // Whole amounts read better without trailing zeros in a report full of
+  // figures; fractional ones keep their precision.
+  const isWhole = Number.isInteger(major);
+  if (isWhole) {
+    return formatterFor(currency, locale)
+      .formatToParts(major)
+      .filter((part) => part.type !== 'decimal' && part.type !== 'fraction')
+      .map((part) => part.value)
+      .join('');
+  }
+
+  return formatter.format(major);
+}
+
+/** The currency's symbol on its own, for compact labels like a stat tile. */
+export function currencySymbol(currency = 'NGN', locale) {
+  const resolved = locale ?? DEFAULT_LOCALES[currency] ?? 'en-US';
+  try {
+    return (
+      formatterFor(currency, resolved)
+        .formatToParts(0)
+        .find((part) => part.type === 'currency')?.value ?? currency
+    );
+  } catch {
+    return currency;
+  }
+}

package/src/runner.js

@@ -8,25 +8,61 @@
  *   - Wrap scenario errors with useful context
  *   - Emit a final 'summary' event when the scenario completes
  *
+ *   - Install the run's random source when a seed is given
+ *   - Enforce the outbound request rate limit
+ *
  * Non-responsibilities:
  *   - The runner does NOT know about HTTP, LLMs, faker, or specific scenarios.
  *     Every concrete behaviour lives in a scenario or an adapter.
  */
 
+import { withSeed, withLocale } from './utils/random-source.js';
+import { throttleTarget, applyLimiter } from './utils/throttle.js';
+
+/**
+ * Ceiling on outbound requests per second, applied to every scenario unless
+ * overridden. High enough that the shipped scenarios never touch it, low
+ * enough that a `delayMs: 0` typo against a real host stays a simulation
+ * rather than becoming a denial-of-service. Pass `Infinity` to disable.
+ */
+export const DEFAULT_MAX_REQUESTS_PER_SECOND = 25;
+
 export class Runner {
   async run(scenario, config) {
     const startedAt = Date.now();
 
+    // Deprecation notices are collected before `emit` exists and flushed once
+    // it does, so option migration can happen before validation.
+    const deprecations = [];
+    const emitDeprecation = (message) => deprecations.push(message);
+
+    const userOptions = migrateLegacyOptions(scenario, config.options, emitDeprecation);
+    assertKnownOptions(scenario, userOptions);
+
     const options = {
       ...(scenario.defaultOptions ?? {}),
-      ...(config.options ?? {}),
+      ...userOptions,
     };
 
     const onEvent = config.onEvent ?? (() => {});
     const signal = config.signal ?? new AbortController().signal;
 
+    // Every scored response already flows through `emit`, so the runner can
+    // collect latency and reason-code data without any scenario cooperating —
+    // and a scenario cannot forget to report it.
+    const latencies = [];
+    const reasonCounts = new Map();
+
     // Wrap onEvent so we never let a buggy subscriber crash the runner.
     const emit = (event) => {
+      if (event?.type === 'response') {
+        if (Number.isFinite(event.latencyMs)) latencies.push(event.latencyMs);
+        for (const reason of event.response?.reasons ?? []) {
+          const code = typeof reason === 'string' ? reason : reason?.code;
+          if (code) reasonCounts.set(code, (reasonCounts.get(code) ?? 0) + 1);
+        }
+      }
+
       try {
         onEvent(event);
       } catch (err) {
@@ -36,17 +72,53 @@ export class Runner {
       }
     };
 
+    for (const message of deprecations) {
+      emit({ type: 'warning', message, timestamp: Date.now() });
+    }
+
+    const maxRequestsPerSecond =
+      config.maxRequestsPerSecond ?? DEFAULT_MAX_REQUESTS_PER_SECOND;
+
+    let throttledMs = 0;
+    const onThrottle = (waitMs) => {
+      throttledMs += waitMs;
+    };
+
+    // When several scenarios run in parallel they must share one limiter, or
+    // the ceiling multiplies by the concurrency and "25 requests a second"
+    // quietly becomes a hundred. runSuite passes its shared limiter down.
+    const target = config.limiter
+      ? applyLimiter(config.target, config.limiter, onThrottle)
+      : throttleTarget(config.target, maxRequestsPerSecond, { onThrottle, signal });
+
     const context = {
       options,
-      target: config.target,
+      target,
       llm: config.llm, // optional, used only by adaptive scenarios (v0.2+)
       emit,
       signal,
     };
 
+    if (config.seed != null) {
+      emit({
+        type: 'milestone',
+        message: `Seeded run (seed ${config.seed}) — random choices will replay identically`,
+        timestamp: Date.now(),
+      });
+    }
+
     let report;
     try {
-      report = await scenario.run(context);
+      // A seeded run installs its generator for the whole scenario, across
+      // every await inside it. Unseeded runs use the system source.
+      // Market first, then seed — both are ambient for the whole scenario,
+      // including across every await inside it.
+      const execute = () =>
+        config.seed != null
+          ? withSeed(config.seed, () => scenario.run(context))
+          : scenario.run(context);
+
+      report = config.locale != null ? await withLocale(config.locale, execute) : await execute();
     } catch (err) {
       emit({
         type: 'error',
@@ -59,23 +131,92 @@ export class Runner {
 
     // Normalise the report. Scenarios may return loose shapes; the runner
     // ensures the canonical fields exist so downstream tooling is reliable.
-    const normalised = {
+    //
+    // Derived rates are computed *after* merging the scenario's own fields, so
+    // a scenario cannot accidentally shadow them with a stale value.
+    const merged = {
       scenarioId: scenario.id,
       scenarioName: scenario.name,
+      // 'attack' or 'legitimate'. Reporting reads a block as a success on one
+      // and a false positive on the other, so every report has to say which.
+      traffic: scenario.traffic ?? 'attack',
       startedAt,
       completedAt: Date.now(),
       durationMs: Date.now() - startedAt,
-      attempts: report.attempts ?? 0,
-      blocked: report.blocked ?? 0,
-      stepUp: report.stepUp ?? 0,
-      allowed: report.allowed ?? 0,
-      blockRate:
-        (report.attempts ?? 0) > 0 ? (report.blocked ?? 0) / report.attempts : 0,
-      stepUpRate:
-        (report.attempts ?? 0) > 0 ? (report.stepUp ?? 0) / report.attempts : 0,
+      // Present only when seeded, so a report never implies reproducibility
+      // it does not have.
+      ...(config.seed != null ? { seed: config.seed } : {}),
+      ...(config.locale != null ? { locale: localeIdOf(config.locale) } : {}),
       ...report, // scenarios can add custom fields
     };
 
+    const attempts = merged.attempts ?? 0;
+    const blocked = merged.blocked ?? 0;
+    const stepUp = merged.stepUp ?? 0;
+    const allowed = merged.allowed ?? 0;
+    const errors = merged.errors ?? 0;
+
+    // Attempts that actually came back with a decision. An attempt that failed
+    // on rate limiting, a timeout, or a 5xx is not evidence about the defence
+    // either way, so it is excluded from the rates rather than being counted as
+    // a block (which would make a target look better the more it fell over) or
+    // as an allow (which would make it look worse).
+    const scoredAttempts = Math.max(0, attempts - errors);
+
+    const normalised = {
+      ...merged,
+      attempts,
+      blocked,
+      stepUp,
+      allowed,
+      errors,
+      scoredAttempts,
+      blockRate: scoredAttempts > 0 ? blocked / scoredAttempts : 0,
+      stepUpRate: scoredAttempts > 0 ? stepUp / scoredAttempts : 0,
+      errorRate: attempts > 0 ? errors / attempts : 0,
+      latency: summariseLatency(latencies),
+      // Amounts are minor-unit integers (kobo, cents — structurally the same),
+      // so the neutral name is the canonical one. The naira-flavoured original
+      // is kept because scenarios and downstream callers already use it.
+      ...(merged.estimatedLossKobo != null
+        ? { estimatedLossMinor: merged.estimatedLossKobo }
+        : {}),
+      // Which signals actually fired, most frequent first. The cheapest way to
+      // see whether a rule is earning its place — a code that never appears
+      // across a full suite is either misconfigured or dead.
+      reasonCounts: Object.fromEntries(
+        [...reasonCounts].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      ),
+    };
+
+    if (throttledMs > 0) {
+      emit({
+        type: 'warning',
+        message:
+          `Rate limit held this run back by ${(throttledMs / 1000).toFixed(1)}s ` +
+          `(cap: ${maxRequestsPerSecond}/s). The scenario asked to go faster than the ` +
+          'configured ceiling — raise maxRequestsPerSecond deliberately if that is what you want.',
+        throttledMs,
+        maxRequestsPerSecond,
+        timestamp: Date.now(),
+      });
+    }
+
+    if (errors > 0) {
+      emit({
+        type: 'warning',
+        message:
+          `${errors} of ${attempts} attempts failed before being scored ` +
+          `(${(normalised.errorRate * 100).toFixed(1)}%). Rates below are over the ` +
+          `${scoredAttempts} attempts that were actually scored. Check errorRate ` +
+          'before treating this run as a measurement of the defence.',
+        errors,
+        attempts,
+        errorRate: normalised.errorRate,
+        timestamp: Date.now(),
+      });
+    }
+
     emit({
       type: 'summary',
       report: normalised,
@@ -85,3 +226,145 @@ export class Runner {
     return normalised;
   }
 }
+
+/**
+ * Reject option keys the scenario does not declare.
+ *
+ * Every scenario's surface is its `defaultOptions`. Without this check a typo
+ * — `attemptsPerIP` for `attemptsPerIp` — silently falls back to the default,
+ * and the run completes and reports a number that answers a different question
+ * than the one asked. Failing loudly is the only safe behaviour for a tool
+ * whose output is a measurement.
+ *
+ * Scenarios that declare no `defaultOptions` (custom ones registered via
+ * `registerScenario`) are skipped — there is nothing to validate against.
+ */
+function assertKnownOptions(scenario, userOptions) {
+  if (!userOptions || !scenario.defaultOptions) return;
+
+  const known = Object.keys(scenario.defaultOptions);
+  const unknown = Object.keys(userOptions).filter((key) => !(key in scenario.defaultOptions));
+  if (unknown.length === 0) return;
+
+  const details = unknown.map((key) => {
+    const suggestion = closestMatch(key, known);
+    return suggestion ? `"${key}" (did you mean "${suggestion}"?)` : `"${key}"`;
+  });
+
+  throw new Error(
+    `Unknown option${unknown.length > 1 ? 's' : ''} for scenario "${scenario.id}": ` +
+      `${details.join(', ')}. Valid options: ${known.sort().join(', ')}.`
+  );
+}
+
+/** Nearest known key within a small edit distance, or null. */
+function closestMatch(input, candidates) {
+  const lower = input.toLowerCase();
+
+  // Case-only mistakes are the most common, so check those first.
+  const caseMatch = candidates.find((c) => c.toLowerCase() === lower);
+  if (caseMatch) return caseMatch;
+
+  let best = null;
+  let bestDistance = Infinity;
+  for (const candidate of candidates) {
+    const distance = editDistance(lower, candidate.toLowerCase());
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+
+  // Beyond a couple of edits a "did you mean" is noise rather than help.
+  const threshold = Math.min(3, Math.floor(input.length / 2));
+  return bestDistance <= threshold ? best : null;
+}
+
+/** Levenshtein distance, iterative with a single row. */
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
+    }
+    previous = current;
+  }
+
+  return previous[b.length];
+}
+
+/**
+ * Latency percentiles over the run's scored responses.
+ *
+ * Nearest-rank on a sorted copy — no interpolation, so every reported figure is
+ * a latency that actually occurred rather than an average of two that didn't.
+ */
+function summariseLatency(samples) {
+  if (samples.length === 0) {
+    return { count: 0, min: null, p50: null, p95: null, p99: null, max: null };
+  }
+
+  const sorted = [...samples].sort((a, b) => a - b);
+  const at = (p) => sorted[Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1)];
+
+  return {
+    count: sorted.length,
+    min: sorted[0],
+    p50: at(50),
+    p95: at(95),
+    p99: at(99),
+    max: sorted[sorted.length - 1],
+  };
+}
+
+/** Report the locale as its id, whether it was passed as a code or a pack. */
+function localeIdOf(locale) {
+  return typeof locale === 'string' ? locale.toUpperCase() : (locale?.id ?? 'custom');
+}
+
+/**
+ * Options renamed when the library stopped assuming naira.
+ *
+ * Amounts were always minor-unit integers — kobo and cents are structurally the
+ * same — so only the names were currency-specific. The old names keep working
+ * because the option validator would otherwise reject them outright, turning a
+ * rename into a hard break for every existing caller.
+ */
+const LEGACY_OPTIONS = {
+  amountKobo: 'amountMinor',
+  amountJitterKobo: 'amountJitterMinor',
+  amountPerMuleKobo: 'amountPerMuleMinor',
+  microAmountKobo: 'microAmountMinor',
+  largeAmountKobo: 'largeAmountMinor',
+  bonusKobo: 'bonusMinor',
+};
+
+function migrateLegacyOptions(scenario, userOptions, warn) {
+  if (!userOptions) return userOptions;
+
+  const declared = scenario.defaultOptions ?? {};
+  let migrated = null;
+
+  for (const [legacy, current] of Object.entries(LEGACY_OPTIONS)) {
+    if (!(legacy in userOptions) || !(current in declared)) continue;
+
+    migrated ??= { ...userOptions };
+    // An explicit new-style value wins; the legacy one is ignored, not merged.
+    if (!(current in userOptions)) migrated[current] = userOptions[legacy];
+    delete migrated[legacy];
+
+    warn(
+      `Option "${legacy}" is deprecated — use "${current}". Amounts are minor-unit ` +
+        "integers in whichever currency the run's locale specifies, so the value is unchanged."
+    );
+  }
+
+  return migrated ?? userOptions;
+}

package/src/scenarios/account-drain.js

@@ -37,7 +37,15 @@ export default {
     targetUserId: null, // required
     attackerIp: null, // optional — random if not provided
     withdrawalCount: 5,
-    amountKobo: 4500000, // NGN 45,000 per withdrawal
+    // NGN 120,000 per withdrawal, in kobo.
+    //
+    // Calibration: rule engines commonly gate "new payee, high amount" near
+    // NGN 50,000 and "large amount from a new device" near NGN 100,000 — the
+    // latter often as a hard block. A default below both means the drain runs
+    // to completion against a correctly configured system and the run reports
+    // a failure that is really just an under-powered attack. Lower this to
+    // find where a specific target's amount thresholds actually sit.
+    amountMinor: 12000000,
     delayBetweenWithdrawalsMs: 15000, // 15 seconds
     postLoginPauseMs: 30000, // 30 seconds — attackers move fast after password change
     skipPasswordChange: false,
@@ -155,7 +163,7 @@ export default {
       const wdPayload = buildWithdrawalPayload(
         options.targetUserId,
         {
-          amount: options.amountKobo,
+          amount: options.amountMinor,
           is_new_payee: true,
         },
         {