O método de engenharia reversa

Todo este curso repousa sobre dois mapas — alembic-complete-map.md e hermes-complete-map.md — e uma matriz de fusão derivada deles. Nada disso é confiável a menos que o método que os construiu seja. Esta lição ensina esse método em quatro princípios: o código vence, camadas honestas de profundidade, Proof-Gate em tudo, e builder ≠ validator. É a disciplina por trás da fusão — e generaliza para qualquer base de código que você precise entender de fora.

Sobre o que tudo isto repousa

O curso inteiro — toda decisão de fusão, todo pacote portado — se apoia em três artefatos: dois mapas de engenharia reversa e uma matriz derivada deles. Se o método que os produziu não for confiável, nada construído em cima é. Por isso o método vem primeiro.

00 · O método em uma imagem

Antes dos detalhes, o mapa-mãe. Os quatro princípios não são uma lista solta: eles formam uma cadeia que transforma "li o repositório" em "produzi um mapa confiável". Cada princípio fecha um buraco específico por onde a mentira normalmente entra.

01 · O código vence, sempre

Em linguagem simples: quando o manual e a máquina discordam, acredite na máquina — e escreva no manual onde ele estava errado. Um documento de design descreve intenção; intenção desvia com o tempo. Um mapa de engenharia reversa que confia no doc acima da fonte herda toda mentira que o doc acumulou.

O próprio cabeçalho do mapa declara a regra: ele mapeia "o filesystem real como construído, não a intenção de design no HANDOFF.md — onde os dois divergem, o código vence e a divergência é anotada".

// docs/alembic-complete-map.md — a disciplina, declarada logo no início
// "This document maps the real filesystem as built, not the design intent in
//  HANDOFF.md — where the two diverge, the code wins and the divergence is noted."
// ex.: HANDOFF diz "11 packages / 284 tests"; a árvore tem 19 packages + 1 app,
//      415 tests (npx vitest list -> 415 cases) — o mapa reflete a decomposição
//      real e NOMEIA o desvio.

O desvio, em barras: o que o handoff dizia vs o que a árvore tem

O mapa não esconde a discordância — ele a registra. Dois números do HANDOFF.md estavam desatualizados; o mapa mostra o valor real ao lado do antigo e nomeia o desvio. Repare a distância:

O mapa literalmente registra onde o handoff estava desatualizado (11 vs 19 pacotes, 284 vs 415 testes) e onde um "bug conhecido" estava na verdade corrigido (contrarian-last, lição 16). Essa honestidade é o entregável.

Doc vs fonte, lado a lado

02 · Camadas honestas de profundidade

Em linguagem simples: você não consegue ler cada linha de cada arquivo com a mesma atenção — e fingir que conseguiu é a mentira mais comum da engenharia reversa. A saída honesta não é ler tudo; é declarar em que profundidade você leu cada parte. Pense em profundidade como um orçamento: gaste no que sustenta carga, e diga onde você não gastou.

No mapa do Alembic isso aparece concretamente: a cintura estreita, o funil, o council e o swarm recebem tratamento profundo com citações de linha; a cauda longa (infra, docs, tui, web) recebe um catálogo estruturado (responsabilidade / API / deps / testes / gaps); e desconhecidos genuínos são marcados [uncertain] — por exemplo "[uncertain] se drivers reais de fonte vivem em outro pacote ou ainda não foram implementados" (§7.4) e "[uncertain] se algum teste de infra roda sob vitest" (§7.16). A fronteira é nomeada, não escondida.

A mesma ideia, como orçamento gasto por subsistema

Profundidade é finita. Veja como o orçamento de atenção se distribui: muito nos quatro subsistemas que sustentam carga, um nível estruturado na cauda longa, e um marcador explícito onde a leitura parou.

03 · Proof-Gate em tudo

Em linguagem simples: toda afirmação precisa de um recibo. A nota de método da matriz de fusão é explícita: "Nada aqui é decidido de memória; todo 'o Alembic tem/não tem X' cita evidência do mapa." Um claim é respaldado por um artefato verificável — um file:line que você abre, uma contagem de hits que você reproduz com grep, um teste que existe. É a mesma disciplina de Proof Gate que o próprio motor usa (lição 17), voltada para dentro, sobre a documentação.

• Todo claim não-óbvio cita um caminho e, onde útil, um número de linha — clicável, checável.
• Presença/ausência de capacidade é fundamentada em contagens de hits sobre o mapa ("memory=1 hit incidental; nenhum pacote de memória" ⇒ é um gap genuíno).
• Estado verificado é declarado com o comando que o produziu ("npx vitest list → 415 casos").

O portão: claim → citação → falsificável (ou volta)

Cada afirmação passa por um portão antes de entrar no mapa. Se ela traz uma citação que um cético consegue abrir e checar, passa. Se não traz, ela não é um fato — é uma asserção, e volta para virar verificável ou ser cortada.

Como um gap vira fato: a contagem de hits

"O Alembic não tem memória" parece uma afirmação de memória — e seria, se fosse só dita. O método a transforma em prova com uma contagem reproduzível sobre as 1488 linhas do mapa: a palavra memory aparece 1 vez, e de forma incidental; não há pacote de memória na seção 7. Esse 1 é o recibo que torna o gap um fato.

04 · Builder ≠ validator

Em linguagem simples: quem faz não é quem confere. A mesma separação que o motor impõe (o Verifier da lição 18, o Validator Gate da lição 17) governa o próprio trabalho de documentação. O curso que você está lendo foi escrito por um agente e revisado por outro — o brief que produziu estas lições declara "Builder ≠ validator" como regra dura. Um mapa checado apenas pelo seu autor herda os pontos cegos do autor; um revisor independente é a versão humana-e-agentic do Verifier read-only.

O análogo: o Verifier read-only do motor, aplicado à documentação

A separação não é nova — é a mesma que o motor já enforce internamente. O Verifier (lição 18) e o Validator Gate (lição 17) são checagens read-only feitas por algo que não produziu o trabalho. Aplicar isso à própria documentação é só estender a disciplina do código para a prosa.

Os quatro princípios como camadas de defesa — e o que vaza se você tira uma

Cada princípio é uma camada que bloqueia uma forma específica de o mapa mentir. Removida uma camada, a mentira que ela parava volta a passar. Por isso os quatro são necessários juntos, não um buffet de boas práticas opcionais.

O payoff concreto: construir sem reler 30k linhas

A recompensa do método não é estética — é alavancagem. Um mapa confiável do Hermes virou a interface sobre a qual a fusão foi construída: a matriz decidiu o que portar, e o pacote real foi escrito a partir do mapa, sem que ninguém precisasse reler todas as 30k+ linhas de Python do Hermes primeiro. O mapa pagou o custo de leitura uma vez; todo trabalho seguinte gastou o mapa, não a fonte bruta.

05 · O método inteiro, em um fluxograma

Junte os quatro princípios numa única rotina. Diante de qualquer base de código desconhecida, siga estas setas: cada losango é uma pergunta que escolhe o caminho, e o ciclo só termina quando o mapa está pronto para ser confiado — não apenas escrito.

06 · Confiança ganha: o que sobe quando você cita

Os princípios têm um efeito mensurável: quanto maior a fração de claims com recibo (citação checável), mais o mapa é confiável — e menos ele depende da fé do leitor. Arraste o slider e veja a confiança subir enquanto a "área de fé" encolhe. É uma ilustração da relação, não uma métrica do repositório.

07 · Aplique a um repo qualquer (passo a passo → agora você)

Você viu os quatro princípios e o fluxograma. Agora rode o método na mão sobre um repositório novo, devagar — depois um passo é seu. Recuperar o procedimento (não só lê-lo) é o que fixa.

Mapa vs ensaio: o que a disciplina compra

A diferença entre um mapa e um ensaio bem escrito não é o estilo — são os recibos. Veja o contraste:

08 · Como isso se encaixa

As outras lições ensinam peças do motor — a cintura, o funil, os gates, o swarm. Esta lição é diferente: ela ensina a peça que produziu o curso inteiro. O método de engenharia reversa não roda dentro de uma execução do Alembic; ele é a disciplina que, aplicada por fora, gerou os dois mapas, a matriz de fusão derivada deles e — por extensão — cada uma das 30 lições que você está lendo. É a única peça do curso cujo "downstream" é o próprio curso.

Onde você está na metodologia: a pipeline de produção corre da esquerda para a direita — os quatro princípios (o método) leem a fonte uma vez e destilam dois mapas; os dois mapas alimentam a matriz de fusão; e os três artefatos juntos autorizam tanto o pacote @alembic/hermes quanto este curso. Clique nos passos abaixo para acender o fluxo nó a nó, ou veja o mapa interativo completo em a metodologia (mapa interativo) →.

As peças que esta lição conecta — cada link abre a lição irmã, com o porquê da ligação:

09 · Na prática

Sinceridade primeiro: não existe um único comando alembic <método> que "faça engenharia reversa" — o método é uma disciplina humana-e-agentic, não um subcomando. [uncertain] Mas três de seus quatro princípios têm um análogo executável no repositório, e é isso que você roda para provar que aplicou o método. O Proof-Gate do método é, literalmente, a baseline de build do repo.

1 · O Proof-Gate, como comando

O princípio 3 ("todo claim traz recibo") tem um recibo canônico para o repositório inteiro: a baseline que tem que ficar verde. É o comando que o próprio CLAUDE.md declara como obrigatório a cada mudança.

# o Proof-Gate do repositório — a baseline que todo claim sobre "está verde" cita
pnpm -r typecheck && pnpm -r build && pnpm -w test

# saída esperada (forma; números variam conforme o estado da árvore):
#   Tasks: N successful, N total      (turbo: typecheck + build em todos os pacotes)
#   Test Files  NN passed (NN)
#   Tests       415 passed (415)      <- o "estado verificado" do mapa, reproduzível
#   exit code 0  -> o gate passou; qualquer não-zero falha fechado

Esse 415 é exatamente o recibo que a Lição (seção 01) cita como "estado verificado": não é uma lembrança, é a saída de um comando que qualquer cético reproduz.

2 · Coerência da árvore real, como comando

O princípio 1 ("o código vence") exige confrontar o que a fonte de fato declara com o que os docs afirmam. Para a camada de modelos/adapters há um comando real que valida a forma declarada contra a implementação — offline, $0, sem rede:

# valida o MODEL_REGISTRY + coerência de adapters contra o código real (offline, sem rede)
alembic doctor --client-stack

# saída esperada (forma): um relatório de checagens, cada uma OK/FALHA,
# fail-closed se a forma declarada divergir da implementação.
# [uncertain] doctor cobre a camada de modelos/adapters, NÃO "o método" inteiro;
# é o análogo executável MAIS PRÓXIMO de "a fonte tem que bater com o doc", não o método em si.

3 · A fronteira e o builder ≠ validator não são comandos

Os princípios 2 (camadas honestas) e 4 (revisor independente) não têm um subcomando — são disciplina de leitura e de processo. O artefato deles vive no repositório como prosa verificável: os mapas em docs/.

# os dois mapas que o método produziu — leia o cabeçalho de disciplina e os marcadores [uncertain]
docs/alembic-complete-map.md      # cabeçalho "the code wins … divergence is noted"; §7.4 e §7.16 marcados [uncertain]
docs/hermes-complete-map.md       # o mapa do Hermes sobre o qual a matriz e o pacote foram construídos
docs/alembic-hermes-fusion-matrix.md  # nota de método: "nothing here is decided from memory"

# reproduza um "gap fundamentado" você mesmo (o Proof-Gate do princípio 3, na mão):
grep -c "memory" docs/alembic-complete-map.md   # a contagem de hits que torna "falta memória" um fato, não uma opinião

[uncertain] o número exato de hits do grep depende da versão atual do mapa; o ponto do método é que o número é reproduzível — não que seja um valor fixo. Rode e use o que sair como o recibo.

Confusões comuns

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.