Round eight: “issue cards”

// deadline propagation: each step gets what is actually left, not a
// fixed timeout that could collectively exceed the budget.
async function authorise(msg: AuthMessage): Promise<AuthResponse> {
  const deadline = Date.now() + 1000;
  const left = () => deadline - Date.now();

  const card = await cards.lookup(msg.token, { timeout: Math.min(50, left()) });
  if (!card || card.state !== 'active') return decline('57');

  const vel = await limits.check(card, msg.amount, { timeout: Math.min(50, left()) });
  if (!vel.ok) return decline('61');

  // fraud FAILS OPEN. an unavailable model must not decline good business;
  // the asynchronous path in Part 9 catches what the fast path misses.
  const risk = await fraud.score(msg, { timeout: Math.min(150, left()) })
    .catch(() => ({ action: 'allow', degraded: true }));
  if (risk.action === 'block') return decline('59');

  // the hold FAILS CLOSED via stand-in: see the next chapter.
  const hold = await ledger.placeHold(card.accountId, msg.amount, {
    timeout: Math.min(250, left())
  }).catch(() => standIn.decide(card, msg));

  return hold.approved ? approve(hold.id) : decline('51');
}

interface StandInPolicy {
  maxPerTransaction: bigint;        // e.g. ₦20,000
  maxPerCardDuringOutage: bigint;   // e.g. ₦50,000
  maxTransactionsPerCard: number;   // e.g. 5
  requireSnapshotAge: number;       // decline if snapshot older than 300 s
  // merchant categories we refuse to stand in for: unrecoverable
  // or high-risk. cash, crypto, gambling.
  blockedMcc: string[];
}

-- the idempotency key that makes clearing-file reprocessing safe.
-- schemes DO redeliver files, and operators DO re-run failed batches.
INSERT INTO journal (id, kind, idempotency_key)
VALUES ($jid, 'card.capture',
        'clr:' || $schemeRef || ':' || $clearingDate);
-- a redelivered file hits the unique constraint and posts nothing.
-- same pattern as the accrual batch in Part 5: make the key carry
-- enough identity that a re-run is provably a no-op.

// selecting the funding account: prefer a matching currency wallet,
// which avoids conversion entirely. this is a real customer benefit and
// it costs us the FX spread we would otherwise have earned, so it is a
// deliberate product choice rather than an oversight.
function selectFunding(card: Card, txCcy: string): Account {
  const match = card.wallets.find(w => w.currency === txCcy && w.available > 0n);
  if (match) return match;                // no conversion: cheapest for them
  return card.wallets.find(w => w.currency === card.billingCurrency)!;
}

CREATE TABLE disputes (
  id              UUID PRIMARY KEY,
  journal_id      UUID NOT NULL,     -- the disputed capture
  reason_code     TEXT NOT NULL,     -- scheme-defined, drives evidence needed
  stage           TEXT NOT NULL,     -- raised|chargeback|representment|arbitration
  amount          BIGINT NOT NULL,
  currency        CHAR(3) NOT NULL,
  -- the single most operationally important column in the table.
  -- a missed deadline is an automatic loss, so this drives alerting.
  stage_deadline  TIMESTAMPTZ NOT NULL,
  provisional_credit_journal UUID,
  outcome         TEXT,             -- won | lost | withdrawn
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX disputes_due ON disputes (stage_deadline)
  WHERE outcome IS NULL;   -- the queue that must never be starved