Round nine: “stop the fraud”

// rules are DATA, versioned and effective-dated, exactly like the
// compliance policies in Part 7. same reasoning: they change on an
// attacker's timetable, not a release schedule.
interface Rule {
  id: string;
  version: number;
  when: Condition;          // a tree over features, no arbitrary code
  then: 'allow' | 'review' | 'block' | 'step_up';
  weight: number;           // contribution when combined with a model score
  // shadow mode: evaluate and record, but do not act. every new rule
  // runs here first so its true false-positive rate is measured on
  // real traffic BEFORE it can decline anybody.
  mode: 'shadow' | 'active';
  effectiveFrom: Date;
  effectiveTo?: Date;
}

// a compact per-account baseline, cheap to store for 20M accounts
interface Baseline {
  accountId: string;
  // distribution, not just a mean: the percentiles are what matter
  amountP50: bigint; amountP95: bigint; amountP99: bigint;
  txPerDayP95: number;
  // the shape of their week, learned rather than assumed
  activeHours: number[];          // 24 buckets of relative frequency
  activeDays: number[];           // 7 buckets
  knownBeneficiaries: number;
  knownDevices: number;
  typicalChannels: string[];      // app | ussd | pos | card | api
  // a baseline built on 3 transactions is not a baseline. say so.
  sampleSize: number;
  confidence: 'low' | 'medium' | 'high';
  computedAt: Date;
}

-- one atomic Lua script: trim the window, count, then add.
-- doing this as separate calls is the Part 2 lost update, again.
local key, now, window, limit = KEYS[1], ARGV[1], ARGV[2], ARGV[3]

-- drop everything older than the window
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)

local count = redis.call('ZCARD', key)
if count >= tonumber(limit) then
  return {0, count}                      -- denied
end

-- member must be unique per event, or two events at the same
-- millisecond collapse into one and the count under-reports.
redis.call('ZADD', key, now, ARGV[4])
redis.call('EXPIRE', key, math.ceil(window / 1000) + 60)
return {1, count + 1}

// ONLINE, on the synchronous path, single-digit milliseconds.
// these are precomputed or counter-based, never traversals.
interface OnlineGraphFeatures {
  beneficiaryIsFlaggedMule: boolean;      // set membership
  deviceAccountCount: number;             // counter
  hopsToNearestConfirmedMule: number;     // materialised nightly
  beneficiaryInboundSources24h: number;   // counter
}

// BATCH, hours, over the whole graph. results are materialised back
// into the online store so the fast path never traverses anything.
//   - connected components over the transfer graph
//   - community detection, e.g. Louvain
//   - PageRank-style centrality to find collection points
//   - path distances to every confirmed mule

// the circuit breaker on our own enforcement. it is the difference
// between a bad rule and a bank-wide incident.
async function enforceBlock(target: Target, reason: Reason) {
  const rate = await counters.increment('blocks:global', { window: 60 });

  if (rate > BLOCK_RATE_CEILING) {
    // we are probably the problem, not the customers.
    await alerts.page('fraud.block_rate_exceeded', { rate });
    await flags.disable('fraud.auto_block');
    return { blocked: false, reason: 'enforcement_suspended' };
  }

  // narrowest effective scope, and an expiry by default
  return blocks.create({
    scope: narrowestScopeFor(reason),
    target,
    expiresAt: addHours(now(), 24),   // requires human confirmation to persist
    createdBy: 'automated',
    reason
  });
}

CREATE TABLE account_restrictions (
  id           UUID PRIMARY KEY,
  account_id   UUID NOT NULL,
  state        TEXT NOT NULL,
  -- WHY, in a form that can be shown to a customer and an auditor
  reason_code  TEXT NOT NULL,
  reason_detail TEXT,
  -- WHO: automation, an analyst, or a court. drives who may lift it.
  imposed_by   TEXT NOT NULL,   -- automated | analyst:id | legal
  -- automated restrictions EXPIRE. legal ones do not.
  expires_at   TIMESTAMPTZ,
  lifted_at    TIMESTAMPTZ,
  lifted_by    TEXT,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- the restriction is checked on the posting path, and it is checked
-- against the DIRECTION of the entry, not merely its existence.
CREATE INDEX restr_active ON account_restrictions (account_id)
  WHERE lifted_at IS NULL;