Enforce Cost Contracts for Paid API Calls

runaway-guard treats dollar cost as a third complexity dimension alongside time and space for any code that calls a paid AI/inference API. Its Iron Law: no call to a paid API without a written $-cap at both the code and provider level - a code-only cap can be bypassed by a bug, a provider-only cap degrades the product mid-use, so both are required. Before writing a call site it forces seven things stated in order: provider and unit cost, a literal max-calls-per-run integer, max $ per run (calculated, not estimated), a max $ per day provider hard cap, a concurrency limit (in code, at the queue, and at the provider), a retry policy (max attempts, which codes retry, idempotency strategy), and an "amplifier audit" against six named runaway shapes - self-rescheduling jobs, webhook handlers calling back the API that triggered them, unbounded recursion over LLM output, polling without a deadline, streaming reconnect storms, and cache-miss stampedes.

Use it when writing or reviewing code that calls a paid AI/inference API (@fal-ai/*, @anthropic-ai/sdk, openai, replicate, elevenlabs, together-ai, groq-sdk, cohere-ai, @mistralai/*) in a loop, queue, retry path, agent step, webhook handler, or background job; when designing a fan-out pipeline or self-rescheduling job; when auditing a codebase for unbounded fan-out or missing spend caps; or when diagnosing an unexpected bill.

The canonical worked example is an Inngest function fanning out Promise.all over image-generation calls with no concurrency limit: a bug in fetchPrompts doubled the prompt list on every retry, and unbounded concurrent Fal.ai calls turned a transient DB error into a ~$200 overnight bill. The fix pattern is a // cost contract: comment stating unit cost, max calls per run, max $ per run, and the provider hard-cap setting, a named MAX_IMAGES_PER_RUN constant instead of trusting list length, p-limit plus matching Inngest concurrency: { limit: N }, an idempotency key per (campaignId, promptHash), and NonRetriableError for oversized input rather than partial processing:

const MAX_IMAGES_PER_RUN = 50;
const limit = pLimit(3);
export const generateCampaign = inngest.createFunction(
  { id: 'gen-campaign', concurrency: { limit: 3 }, retries: 2 },
  { event: 'campaign/start' },
  async ({ event, step }) => {
    const prompts = await step.run('fetch', () => fetchPrompts(event.data.id));
    if (prompts.length > MAX_IMAGES_PER_RUN) {
      throw new NonRetriableError(`prompt count ${prompts.length} exceeds MAX_IMAGES_PER_RUN=${MAX_IMAGES_PER_RUN}`);
    }
    await Promise.all(prompts.map(p => limit(() => step.run(
      `img:${event.data.id}:${sha1(p)}`,
      () => fal.run('fal-ai/flux-pro', { input: { prompt: p } })
    ))));
  }
);

A verification checklist gates shipping: a cost-contract comment per call site, a named integer bound (not implicit list length), concurrency set in code and at the queue, an explicit retry policy, a documented provider dashboard hard cap, per-environment API keys, a completed amplifier audit, and tests for empty input, oversized input, 4xx non-retry, and idempotency dedup.

A provider cheat sheet names exactly where to set the hard cap: Fal.ai's Billing → Spend Limit, Anthropic's per-Workspace Budget with a hard limit, OpenAI's org-level Usage limits (project-level budgets are documented as soft-only alerts, not a real block), Replicate's account-wide Spend limit, and ElevenLabs' per-key Usage limits, plus Inngest's concurrency/retries settings as the queue-layer multiplier to bound. Related sibling skills: invariant-guard for the termination-measure precondition, complexity-cuts for diagnosing an already-shipped runaway, lemmaly for picking the algorithm before applying the wallet invariant, and mathguard for compute-cost problems rather than per-call billing.

Eight rationalizations are named and rebutted so they cannot be used to skip the discipline - 'I'm only testing locally' (local hits the same paid endpoint), 'the list is small' (it grows), 'Inngest already retries' (retries multiply across layers rather than replacing each other), and 'we have monitoring, we'll catch it' (monitoring catches it after the money is already spent) among them - alongside eight red-flag code shapes to stop and fix before writing further, such as an unbounded Promise.all over a paid call or a retry wrapper duplicating a framework's own retries. Stated limitations matter for applying the discipline correctly: it enforces intent at code-write time rather than metering spend at runtime, provider-side caps reconcile on a delay of minutes rather than milliseconds, it maintains no per-model price table so unit costs must be looked up by the author, per-token APIs (Anthropic, OpenAI) need max tokens per run in place of max calls per run since token count is the real cost driver, and long-running GPU-billed jobs need GPU-seconds in place of calls while the same discipline transfers.

Developers and reviewers writing or auditing any code path that calls a billed AI API in a loop, agent step, webhook, or background job, who want a concrete, checkable discipline for bounding dollar cost rather than discovering the bound after a surprise bill.