runaway-guard — Custo é a Terceira Dimensão da Complexidade

Todo loop tem complexidade de tempo e complexidade de espaço. Um loop que chama uma API paga tem uma terceira: dólares por execução. O modelo rastreia as duas primeiras automaticamente. Ele não rastreia a terceira, então entrega código onde um único bug — uma nova tentativa sem limite, uma tempestade de reconexão de stream, um agente que se reenfileira, um webhook que dispara o mesmo job duas vezes — gasta silenciosamente dinheiro real.

O incidente canônico: um desenvolvedor escreve um loop de geração de imagem Fal.ai. O loop "termina obviamente" porque itera sobre uma lista fixa. A lista vem de um callback que dispara em cada nova tentativa do Inngest. Cada nova tentativa dobra a lista. Pela manhã, a conta é de $200. Testes passam. Revisão de código passou. O bug não está no corpo do loop. O bug é que ninguém declarou o invariante da carteira.

runaway-guard corrige isso. Declare as chamadas máximas. Declare os dólares máximos por execução. Declare os dólares máximos por dia. Defina os mesmos limites no painel do provedor para que um bug de código não possa contorná-los. Então escreva o código.

Violar a letra destas regras é violar o espírito da habilidade. "Estou apenas testando localmente" é a exata racionalização que entrega a conta de $200 — o código local atinge a mesma API paga que a produção.

Quando Usar Esta Habilidade

Use runaway-guard quando:

• Escrever ou revisar código que chama uma API paga de IA / inferência em um loop, fila, caminho de nova tentativa, etapa de agente, manipulador de webhook ou job em segundo plano.
• Importar ou encapsular qualquer SDK de inferência paga: @fal-ai/*, fal-client, @anthropic-ai/sdk, anthropic, openai, replicate, elevenlabs, together-ai, groq-sdk, cohere-ai, @mistralai/*.
• Projetar um loop de agente, pipeline fan-out, wrapper de nova tentativa, job de polling, reconexão de stream ou job de auto-reagendamento que possa chamar um endpoint cobrado.
• Auditar uma base de código / PR para fan-out ilimitado, novas tentativas ilimitadas, chaves de idempotência ausentes ou limites de gastos do provedor ausentes.
• Diagnosticar uma conta inesperada, incidente de loop descontrolado ou excedente surpresa.

A Lei de Ferro

NO CALL TO A PAID API WITHOUT A WRITTEN $-CAP AT BOTH THE CODE AND PROVIDER LEVEL

Um limite apenas no código pode ser contornado por um bug nesse código. Um limite apenas no provedor pode ser atingido durante o uso normal e degradar o produto. Você precisa de ambos. Se você não consegue declarar ambos em uma frase cada, você não projetou o local da chamada — você escreveu um desejo.

Regras Inegociáveis

1. Cada local de chamada recebe um contrato de custo de uma linha. Antes de escrever qualquer chamada de API paga, declare em uma frase:

   • Máx. chamadas por execução: o limite superior estrito de invocações em uma única execução deste caminho de código.
   • Máx. $ por execução: max_calls × unit_cost — calcule, não estime.
   • Máx. $ por dia: o limite rígido do lado do provedor que garante o limite do lado do código.

   Exemplos:

   • "Fal flux-pro a $0.05/imagem; máx. 20 imagens por job; máx. $1 por job; Limite de Gastos do provedor $50/dia."
   • "Anthropic Sonnet a ~$0.015 por solicitação (em cache); máx. 50 solicitações por execução de agente; máx. $0.75 por execução; Orçamento de Espaço de Trabalho limite rígido $30/dia."

   Se você não consegue preencher todos os três números, você não projetou o local da chamada.

2. Todo loop que chama uma API paga recebe um limite de iteração explícito, não apenas um argumento de terminação. invariant-guard requer uma medida de terminação. runaway-guard requer que o limite seja um inteiro concreto em código, não apenas "termina eventualmente":

   // ❌ Terminates in theory. Bills $200 in practice.
   while (job.status !== 'done') {
     await fal.run(...);
   }
   
   // ✅ Concrete bound — wallet invariant explicit.
   const MAX_CALLS = 20;
   for (let i = 0; i < MAX_CALLS && job.status !== 'done'; i++) {
     await fal.run(...);
   }
   if (job.status !== 'done') throw new Error('exceeded MAX_CALLS budget');
   

3. Todo caminho de nova tentativa é limitado por tentativas E custo total decorrido, não apenas por tempo. Backoff exponencial sem limite de tentativas é um ataque à carteira contra você mesmo.

   • Máx. tentativas: um inteiro pequeno (3–5 para erros transitórios, 1 para 4xx).
   • Limite as contagens em todo o pipeline, não apenas em uma biblioteca — novas tentativas do Inngest × novas tentativas do SDK × seu próprio wrapper de nova tentativa se multiplicam.
   • Erros 4xx não tentam novamente. Ponto final. Eles não se tornarão 2xx; eles apenas cobrarão novamente.

4. Todo caminho fan-out declara um limite de concorrência. Chamadas paralelas multiplicam o custo por segundo de relógio de parede. Declare o limite em código, na fila (Inngest concurrency) e no provedor onde suportado:

…