A cintura estreita: um run() que nunca lança

Imagine um prédio inteiro com uma só porta giratória. Cada pessoa que entra ou sai — não importa de qual sala, andar ou setor — passa por aquela única porta. Se a porta for confiável, o prédio é confiável. A cintura estreita é essa porta: o ponto fino por onde toda chamada de modelo do Alembic obrigatoriamente passa.

A cintura estreita como ampulheta — toda chamada de modelo passa por uma porta só.

O contrato é uma união discriminada sobre um campo literal ok. Não existe throw no tipo — falha é um valor, não um evento de controle de fluxo:

packages/contracts/src/model.ts — os dois ramos (condensado)

type ModelRunSuccess = {                  // ok: literal(true) é o discriminante
  ok: true; adapterId: string; durationMs: number; modelId: string;
  text: string; usage?: TokenUsage; costUsd?: number; raw?: unknown;
};
type ModelRunFailure = {                  // ok: literal(false)
  ok: false; adapterId: string; durationMs: number; modelId: string;
  error: { code: string; message: string; retryable: boolean };
};
type ModelRunResult = z.discriminatedUnion('ok', [Success, Failure]);

O chamador escreve if (result.ok) e o TypeScript estreita o tipo. Crucialmente, o ramo de falha carrega um retryable: o ponto de chamada não precisa adivinhar se um 429 vale a pena repetir — o resultado já diz. A própria interface documenta a lei: run(input): Promise<ModelRunResult> // NUNCA lança (invariante).

Um comentário dizendo "nunca lança" não vale nada se um adapter esquecer. Então o invariante é estrutural: cada adapter implementa apenas um attempt() interno, e um único spine compartilhado — runWithGuards — o embrulha com quatro camadas, em ordem:

As quatro guardas em ordem, de fora para dentro — só o miolo (attempt) é escrito por cada adapter.

packages/adapters/src/adapter-core.ts:118-147 — o spine canônico (condensado)

export const runWithGuards = async (adapterId, attempt, input, runtime = {}) => {
  const validation = validate(adapterId, input);          // ① Zod no boundary
  if (!validation.ok) return validation.result;         //    input ruim ⇒ Failure, não throw
  try {
    return await withRetry(                                // ③ backoff em resultados retryable
      () => guardedAttempt(adapterId, attempt, input, runtime.breaker, logger), // ②
      policy, { clock, logger, random: runtime.random, signal: input.signal },
    );
  } catch (cause) {
    // withRetry só rejeita se guardedAttempt rejeitar, o que ele nunca faz;
    // esta é uma rede de segurança final para preservar o invariante.
    return failureFromThrown({ adapterId, input, durationMs: 0 }, cause); // ④
  }
};

A camada ② é onde o circuit-breaker aprende. guardedAttempt chama breaker?.recordSuccess() num resultado ok e breaker?.recordFailure() caso contrário, e reporta retry: true só quando result.error.retryable (adapter-core.ts:103-110). E há um caminho que nem chega a tentar: se o breaker já estiver aberto, guardedAttempt retorna cedo com circuit_open — protege um provedor que já está caído de levar mais carga.

Por que classificar a "repetibilidade" na fonte? Porque o adapter conhece o provedor. Um 429 (rate limit) ou um 5xx transitório são retryable: true; um 400 (input inválido) ou 401 (sem credencial) são retryable: false — repetir só desperdiça. Classificar uma vez, na fonte, mantém a política uniforme e impede que cada ponto de chamada reinterprete o erro à sua maneira (o que levaria a drift).

Existe uma segunda união discriminada, mais leve — também sobre ok, com ramos value/error — para todo trabalho falível que não é chamada de modelo: IO de arquivo, parsing, wrapping de subprocesso. Ela espelha de propósito a cintura do modelo, para que ambas se leiam igual nos pontos de chamada:

packages/contracts/src/result.ts — o irmão leve

type Result<T, E = Error> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly error: E };
// helpers: ok(v), err(e), isOk, isErr, mapResult, tryCatch, tryCatchAsync

Este é o Result<T, Error> que você viu sendo devolvido por todo subsistema @alembic/hermes nas lições 7–13 — load(), transcribe(), webSearch() todos devolvem ele. A regra do repositório é explícita: "código de biblioteca devolve Result em vez de lançar" (CLAUDE.md). Duas uniões, uma filosofia: falibilidade é um valor, validado no boundary, nunca uma surpresa.

Cinco cartas, a lição inteira. Use as setas do teclado ou os botões.