O motor

Um motor que destila: barato primeiro, caro só no que sobrevive

Uma pilha onde as dependências só apontam para baixo

O Alembic é organizado em camadas de cima para baixo, e a organização é real: o grafo de imports não tem nenhuma aresta para cima e nenhum ciclo. Cada camada só pode depender das que estão abaixo. Leia de baixo para cima — a fundação é o vocabulário; o topo é onde humanos e ferramentas se conectam.

As seis camadas, de L4 (clientes, no topo) a L-1 (ingestão, na base). A seta à direita é a regra inteira: dependências apontam só para baixo.

Cola que atravessa as camadas. Alguns pacotes orquestram através de L2–L4 e se leem melhor como um tier próprio: @alembic/mission (compila missões → run specs), @alembic/vm (executa o alembic.plan.ts injetando os hooks h.*), @alembic/coda (os quatro gates que fecham o run), @alembic/forge (o front-end Forge + Scope Gate) e @alembic/planf3 (o HTML do plano).

Um contrato que nunca lança

// INVARIANTE: ModelAdapter.run NUNCA lança.
interface ModelAdapter {
  run(input: ModelRunInput): Promise<ModelRunResult>;   // nunca lança
}
// ModelRunResult é uma união discriminada em `ok`:
ModelRunSuccess = { ok: true;  text; usage?; costUsd?; durationMs; modelId; ... }
ModelRunFailure = { ok: false; error: { code; message; retryable }; durationMs; ... }
ModelRunResult  = z.discriminatedUnion('ok', [ Success, Failure ])

Existe ainda uma segunda união, mais leve, Result<T, E> (também em ok, com braços value/error) para trabalho falível que não é de modelo — IO de arquivo, parsing, wrapping de subprocesso. Ela espelha de propósito a cintura de modelo, para os dois se lerem idênticos no ponto de chamada. Essa disciplina é a Lição 5.

"Nunca lança" não é uma esperança — é estrutural

"Nunca lança" não é um comentário que você torce para ser verdade — é imposto estruturalmente por uma única espinha reutilizável, runWithGuards. Cada adapter implementa só um attempt() interno; a espinha o envolve, em ordem, com quatro proteções.

1. Validação Zod do input no boundary — entrada malformada nunca chega ao provedor.
2. try/catch que converte qualquer throw que escapou numa ModelRunFailure tipada.
3. Um circuit-breaker opcional como gate.
4. Retry com backoff, dirigido pela flag retryable de cada resultado — com um try/catch externo final "como última rede de segurança para preservar a invariante".

São exatamente quatro

A arquitetura repousa sobre quatro propriedades (não mais — o mapa enumera exatamente estas). Cada uma é afirmada na fonte, e a maioria é governada por uma ADR.

Uma destilação em quatro tiers, barato primeiro

O funil de quatro tiers. T0 (topo) é gratuito e roda sobre 100% do corpus; cada tier abaixo é medido e vê menos itens, mais fortes.

Explore tier a tier

Três invariantes de segurança que o funil nunca pode regredir: PII antes da saída (um sinal de canal privado é redigido antes da chamada de modelo e re-checado antes de qualquer escrita), budget fail-closed (toda chamada paga é embrulhada num BudgetGuard.check fail-closed — uma quebra projetada bloqueia a chamada e o tier degrada em vez de estourar o gasto) e append-only (resultados fluem para stores endereçados por conteúdo, validados por esquema, append-only; leituras de fonte continuam somente-leitura).

GO sozinho não basta

Três mal-entendidos que valem desfazer

Cinco slides para fixar a forma do motor

Passe pelos slides com os botões, as setas do teclado (← →) ou os pontos. Cada um é um dos pilares desta lição.

Três checagens — pontuadas