Transaction External Call Guard

THE SYMPTOM: under load the app stops responding and the database logs say the connection limit was reached -- while CPU on the app server AND the database are both near idle. Nothing crashed. Nothing errored. Everything is just waiting.

THE CAUSE, ALMOST ALWAYS: something inside a database transaction is awaiting a call to a system you do not control -- a payment provider, an email API, a webhook, an LLM call. The transaction holds its database connection for the ENTIRE time that call is in flight. At ten transactions a second with a two-second third-party call, that is twenty connections permanently occupied doing nothing but waiting on someone else's network.

IT IS NOT A LEAK AND IT IS NOT A DEADLOCK. Every connection is legitimately in use, every transaction will eventually commit, and the pool is exhausted anyway. That is why the usual instincts -- raise the pool size, look for a missing commit, check for long-running queries -- all come back empty. The queries are fast. The TRANSACTIONS are slow, and only because of something that is not a query.

This analyses what a transaction body actually awaits and reports the external calls held inside it, with the arithmetic of what that costs at your throughput -- so the fix is a specific await moved outside a specific transaction, rather than a pool size raised until it happens again at a higher number.

VERIFIED: 61 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function analyzeTransaction( graph: TransactionCallGraph, options: AnalyzeOptions = {}, ): AnalyzeResult;
  export function formatFinding(f: Finding): string;
  export function formatReport(result: AnalyzeResult): string;

  export type IoKind = 'network' | 'filesystem' | 'process' | 'timer' | 'unknown';
  export type CallNodeKind = 'internal' | 'external-io' | 'unresolvable';
  export type Finding = ExternalCallFinding | NotDeterminableFinding;