As quatro invariantes

A arquitetura do Alembic repousa sobre exatamente quatro propriedades — não seis, não "boas práticas", mas quatro invariantes nomeadas, cada uma afirmada no código e a maioria governada por uma ADR: ① run() nunca lança, ② agnóstico a adapter/store, ③ IDs content-addressed + run-dir determinístico, ④ o dissenso é preservado pelo Verifier. São as regras que todo pacote mantém — a razão de o sistema ser testável, reproduzível e confiável. Conhecê-las é conhecer a espinha do motor.

As quatro, em resumo

Comece pelo papel que elas cumprem. As quatro invariantes são o filtro de pertencimento: dado um pacote qualquer do repositório, elas decidem se ele é Alembic ou apenas código que mora no mesmo lugar. Pense num portão de quatro perguntas — basta reprovar em uma e o pacote não passa:

Passado o portão, vale ver como as quatro se organizam. Elas não são uma lista solta: são dois pares que se reforçam. ① e ③ (nunca-lança + content-addressed) tornam a run reproduzível; ② e ④ (agnóstico + dissenso estrutural) tornam a run testável e confiável. Pense numa grade 2×2 — reprodutibilidade no eixo de cima, confiança no de baixo:

E por que "afirmada no código" importa tanto? Porque há uma escala de força. Uma invariante pode viver só num comentário (frágil), num teste (melhor), ou no tipo / no carregamento — onde o compilador ou o motor a recusam antes de rodar. As quatro do Alembic vivem no degrau mais alto: são impostas por construção, não por boa-fé.

① run() nunca lança; o resultado é uma união discriminada uniforme

O contraste é o coração do invariante. À esquerda, o mundo "normal": uma exceção sobe pela pilha e quem não a tratou quebra. À direita, o mundo Alembic: o erro é capturado na fonte e desce como um valor que o chamador tem de olhar:

// a forma do resultado: discriminada em `ok` — nunca um throw
type ModelRunResult =
  | { ok: true;  value: Completion }
  | { ok: false; error: ModelError };   // um 429 chega aqui, não como exceção

E não é só o adapter. O invariante se repete em camadas: o adapter garante a fronteira na chamada de modelo; o núcleo (core.ts) re-estabelece a mesma garantia em volta de council e swarm com runDebateSafe/runSwarmSafe; o servidor (lição 17) a fecha de novo em cada handler HTTP. Um throw em qualquer profundidade é capturado pela fronteira mais próxima e desce como valor:

② Os motores são agnósticos a adapter E a store

Os kernels puros recebem apenas vistas readonly e efeitos colaterais injetados. O DebateEngine, o scoring e o verifier recebem um AdapterRegistry injetado (council/src/debate.ts:71-83). A camada ETL roteia todo IO por um FsPort injetável — "toda função aqui é testável em memória" (etl/src/index.ts:11-14). E o funil recebe um registry de adapters injetado, então trocar por um registry offline torna a run inteira $0 e hermética (funnel.ts:79-81).

// o padrão, em todo lugar: dependências chegam como argumentos, nunca imports de concretos
runDebate({ board, pack, adapters, requestId });   // adapters injetados → teste com fakes
runT0Pipeline(corpusDir, { fs });                   // FsPort injetado → roda em memória
runFunnel(corpusDir, { adapters: offlineRegistry }); // registry offline → $0, hermético

Esta é a lição 5 (portas & injeção) elevada a lei arquitetural: nenhum motor alcança um adapter, filesystem ou store concreto. É exatamente o que faz a suíte de 400+ testes rodar rápido, em memória, sem rede — e o que permitiu testar os subsistemas do @alembic/hermes (lições 7–13) sem abrir um único socket.

O ganho é concreto. Compare um motor amarrado a concretos (precisa de gateway no ar, rede, dinheiro, e fica lento e instável) com o motor injetável do Alembic (fake em memória: rápido, determinístico, $0):

③ IDs content-addressed + layout determinístico de run-dir

O id de uma run é o hash de conteúdo (estilo SHA-256) do seu spec: runIdFor(spec) (swarm/src/orchestrator.ts:168). Mude qualquer campo do spec e você obtém um novo diretório de run — runs são reproduzíveis porque inputs idênticos convergem para o mesmo id e o mesmo lugar no disco (swarm/src/types.ts:247-257: "Changing any field yields a new run directory").

A consequência que importa é o replay. Reexecutar o mesmo spec não cria uma run nova: o hash bate, o run-dir é o mesmo, e o motor retoma/re-deriva ali — convergência. Mude um campo e o hash diverge: nasce um diretório novo, e o antigo fica intacto. Os dois caminhos, lado a lado:

// run dirs: <baseDir>/runs/<runId> · events.jsonl append-only + checkpoint.json
// stores são content-addressed por SHA-256 sobre JSON canônico (chaves ordenadas) →
// re-anexar conteúdo idêntico é no-op, então re-runs convergem em vez de duplicar

Repare na peça que fecha o ciclo: os stores também são content-addressed. canonicalJson ordena as chaves recursivamente e contentHash tira o SHA-256 disso; se o hash já existe no arquivo, appendStoreRecord não escreve de novo — é um no-op (etl/src/stores.ts:79-97,148-166). Conteúdo igual nunca duplica:

É por isso que módulos de plano (alembic.plan.ts) precisam ser determinísticos — Date.now(), new Date() e Math.random() são rejeitados pela VM. Não-determinismo mudaria o hash do spec a cada run e quebraria o replay, então o motor recusa carregar um plano que o contenha (a lição 17 cobre o portão que impõe isso em planos).

Laboratório: o hash decide o run-dir

Sinta o invariante ③ na mão. Ligue/desligue campos do spec abaixo: cada mudança recalcula um hash de demonstração e, com ele, o caminho do run-dir. Repare em duas coisas — o mesmo conjunto sempre dá o mesmo hash (reprodutível), e qualquer alteração dá um hash totalmente diferente (novo diretório, nada sobrescrito).

④ O dissenso é preservado/forçado pelo Verifier, não meramente por um prompt

Este é o mais sutil, e o que mais times erram. Muitos "councils" adicionam um prompt que diz "faça advogado do diabo" e chamam isso de adversarial. O Alembic não confia num prompt para produzir dissenso — ele torna o dissenso estrutural por dois mecanismos:

• O Verifier maker-checker é read-only por arquitetura: aceita apenas vistas readonly, não expõe superfície de adapter ou mutação, e prova claims atômicos com oráculos determinísticos sobre a evidência estruturada (votos, scores, spread, quórum), nunca sobre a prosa do maker (council/src/verifier.ts:19-99).
• "Contrarian-last" é imposto no board-load — contrarian_not_last é um erro duro de carregamento (council/src/board.ts:142-149) — e realizado como sequenciamento real (fases seriais, membros paralelos; debate.ts:30-44,205-210).

O segundo mecanismo merece um diagrama, porque é onde "contrarian-last" deixa de ser uma frase e vira execução. As fases do debate rodam em série (uma depois da outra), mas os membros dentro de uma fase rodam em paralelo. O contrarian é alocado na última fase — então, por construção, ele só fala depois que todos os outros já se posicionaram. Não há prompt pedindo isso: é a ordem em que o motor executa.

Por que "oráculo determinístico" e não "o Verifier lê o argumento do maker"? Porque um oráculo é uma função pura sobre a evidência estruturada — mesma evidência entra, mesmo veredito sai, sem rede e sem modelo. Ele olha votos, scores, spread e quórum; nunca a prosa. Veja a anatomia de uma prova de claim:

As quatro juntas: rastreie uma run (passo a passo → agora você)

As invariantes não agem isoladas — elas se encadeiam numa run real. Siga uma chamada do começo ao fim e veja cada uma entrar em cena. Depois, um caso é seu. Recuperar o encadeamento (não só ler a lista) é o que fixa de verdade.

Quatro, não seis (e nem as três do funil)

Duas armadilhas de contagem rondam estas invariantes. A primeira: o curso antigo dizia "seis" — divergência pura. A segunda é mais sutil e vale fixar: o funil tem suas próprias três invariantes de segurança (docs/alembic-complete-map.md §3) — orçamento que degrada em vez de estourar, escritas append-only/content-addressed/validadas, e leituras read-only na fonte. Essas três são locais ao funil; as quatro desta lição são arquiteturais e valem para todo pacote. Não as some.

O erro de soma fica óbvio quando você desenha os escopos lado a lado: conjuntos diferentes, abrangências diferentes — e um deles simplesmente não existe.

Confusões comuns

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta — e o arquivo que a afirma — antes de virar. Recuperação ativa fixa mais que reler.

Como isso se encaixa

As quatro invariantes não são uma seção isolada do curso: são o chão sobre o qual toda run do Alembic anda. Onde você está na metodologia? Bem embaixo dela. Cada estágio que você já viu — o spec virar run-dir, o motor chamar um adapter, o council debater, os gates julgarem, o loop de aprendizado registrar — repousa sobre uma destas quatro regras. Tire uma e o estágio correspondente perde a garantia: a run pode quebrar (①), virar não-testável (②), divergir a cada execução (③) ou aceitar um consenso sem pressão (④).

O diagrama abaixo mostra o encaixe literal. Em cima, o fluxo de uma run da esquerda para a direita. Embaixo, as quatro invariantes como uma fundação — cada uma sobe e segura o estágio que governa. Use os botões para acender invariante por invariante e ver o que cada uma sustenta.

As invariantes conectam-se a quatro outras lições — cada uma aprofunda uma face desta fundação:

Na prática

Invariante não é teoria de quadro-branco — você consegue tocar duas delas com a CLI, sem custo. O invariante ③ (content-addressed/determinístico) aparece no alembic replay: reexecutar o mesmo run-id retoma o mesmo diretório em vez de criar um novo. E o invariante ① (nunca lança) é exatamente o que a suíte de testes prova — toda falha vira valor tipado, então o teste verifica ramos, não captura exceções.

① nunca lança — a suíte verde é a prova

O baseline de build/teste do projeto roda mais de 400 testes em memória, $0, sem rede. Eles só conseguem rodar assim porque os erros são valores (①) e as dependências são injetadas (②):

# baseline do repositório — tudo verde a cada mudança (CLAUDE.md)
pnpm -r typecheck && pnpm -r build && pnpm -w test

# saída esperada (resumida):
#  ✓ packages/adapters  runWithGuards: um 429 vira { ok:false } (não lança)
#  ✓ packages/council   contrarian_not_last = erro duro de board-load
#  ✓ packages/etl       appendStoreRecord: conteúdo idêntico = no-op
#  Test Files  N passed
#  Tests       400+ passed

Para isolar só um invariante, rode o pacote que o afirma — a saída exata varia com a versão; o que importa é "passed":

# o invariante ① / ② no adapter (a fronteira que não lança)
pnpm --filter @alembic/adapters test
# o invariante ④ no council (Verifier + contrarian-last)
pnpm --filter @alembic/council test
# o invariante ③ no etl (append content-addressed / no-op)
pnpm --filter @alembic/etl test

③ content-addressed — veja o replay convergir

Aqui o invariante ③ fica visível a olho nu. Uma run nasce de um spec; seu id é o hash do conteúdo. Reexecutar pelo mesmo id não bifurca — retoma o mesmo run-dir a partir do events.jsonl + cache:

# 1) liste as runs existentes (cada id É o hash content-addressed do spec)
alembic runs list

# 2) reexecute UMA pelo seu id — replay, não uma run nova
alembic replay <run-id>

# saída esperada (o ponto é a IDENTIDADE do diretório):
#  resume/re-execute from events.jsonl + cache
#  → mesmo <run-id> ⇒ MESMO ~/.alembic/runs/<run-id>/ (nada sobrescrito)
#  conteúdo idêntico re-anexado = no-op (convergência, não duplicação)