O Motor

Antes de qualquer fusão, você precisa do hospedeiro. O Alembic é um motor de execução de planos para enxames de agentes: ele recebe um objetivo, um plano executável e um contrato de validação, então roda unidades de trabalho em vários modelos — roteando por custo, provando cada passo, com portão antes de entregar. Esta lição é a forma dele: seis camadas, um contrato que carrega o peso, quatro invariantes e o funil que transforma fontes brutas em Learnings.

As contagens são verificadas na fonte. O mapa registra 19 pacotes de workspace + 1 app; a suíte estava em 415 quando o mapa foi escrito e cresceu para ~565 depois que @alembic/hermes chegou — os mesmos 565 que o estudo de caso da Lição 6 roda.

As seis camadas

O Alembic é estratificado de cima a baixo, e a estratificação é real: o grafo de imports não tem arestas para cima nem ciclos. Cada camada só pode depender das que estão abaixo. Leia de baixo — a fundação é o vocabulário, o topo é onde humanos e ferramentas se conectam.

Cola que atravessa as camadas. Um punhado de pacotes orquestra através de L2–L4 e é melhor lido como seu próprio nível: @alembic/mission (compila missões → run specs), @alembic/vm (executa alembic.plan.ts injetando os hooks h.*), @alembic/coda (os quatro portões de fechamento de run), @alembic/forge (o front-end Forge + Scope Gate) e @alembic/planf3 (HTML de plano).

A cintura estreita — um contrato que nunca lança

Eis a ideia mais importante do código. Toda invocação de modelo no sistema inteiro flui por uma forma de função: uma chamada async que nunca lança e retorna uma união discriminada chaveada em ok. Sucesso e falha são ambos valores de retorno comuns — não há um segundo caminho excepcional para raciocinar.

// packages/contracts/src/model.ts — a cintura (forma)
interface ModelAdapter {
  run(input: ModelRunInput): Promise<ModelRunResult>;   // NUNCA lança (a invariante)
}
// 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 ])

Fonte: packages/contracts/src/model.ts:30-151. Governado pela ADR-0009 ("cintura estreita — run nunca lança").

"Nunca lança" não é um comentário que você torce para valer — é estruturalmente imposto por uma única espinha reusável, runWithGuards. Cada adapter implementa só um attempt() interno; a espinha o encapsula, em ordem, com: (1) validação Zod da entrada na fronteira, (2) um try/catch que converte qualquer throw escapado em um ModelRunFailure tipado, (3) um portão opcional de circuit-breaker, e (4) backoff de retry guiado pelo flag retryable de cada resultado — com um try/catch externo final "como última rede de segurança para preservar a invariante".

Uma segunda união Result<T, E> mais leve (também chaveada em ok, com braços value/error) existe para trabalho falível não-modelo — IO de arquivo, parsing, encapsular subprocessos. Ela espelha deliberadamente a cintura de modelo para que ambas leiam idêntico nos call sites. Essa disciplina é a Lição 5.

As quatro invariantes — exatamente quatro

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

O funil — uma destilação de 4 níveis

A razão de existir do Alembic é o funil: ele transforma um corpus bruto em duas cadeias de valor — um grafo de oportunidades de negócio e um store de Learnings. Faz isso em quatro níveis de custo, barato-primeiro, para que a maior parte do trabalho custe nada e só os sinais mais fortes cheguem a um modelo pago.

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

Confusões comuns