O método de reverse-engineering
Este curso inteiro se apoia em dois mapas — alembic-complete-map.md e hermes-complete-map.md — e numa 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: tiers de profundidade honestos, Proof-Gate em tudo, builder ≠ validator e "o código vence". É a disciplina por trás da fusão — e generaliza para qualquer código que você um dia precise entender de fora.
Esta lição destila a disciplina declarada dos próprios documentos: o cabeçalho do mapa ("the code wins … divergence noted"), a nota de drift do HANDOFF.md (11→19 pacotes, 284→415 testes), os marcadores [uncertain] e a nota de método da matriz ("Nothing here is decided from memory; every 'Alembic has/lacks X' cites map evidence"). Cada afirmação aqui é citada de arquivo real — nada é inventado.
- Por que, quando o mapa e o
HANDOFF.mddiscordam, o código vence — e a divergência é anotada, não escondida. - Como declarar tiers de profundidade honestos (deep-dive · catálogo · fronteira) em vez de fingir que leu tudo no mesmo nível.
- O que significa Proof-Gate em tudo: todo claim cita um
file:lineque abre, um hit-count que você reproduz, ou um teste que existe. - Por que builder ≠ validator é o análogo documental do Verifier read-only do motor.
- Por que essas quatro disciplinas generalizam para qualquer base de código desconhecida.
- Você já abriu um repositório que não conhecia e tentou entender o que ele faz.
- Você sabe que um README descreve a intenção e que código pode divergir dela. Não precisa decorar o Alembic — usamos ele só como exemplo concreto.
- Você não precisa saber o que é "Proof-Gate", "Verifier" ou "hit-count". Construímos cada termo do zero aqui.
Um mapa de engenharia reversa só vale se for confiável, não só lido. A diferença entre os dois é inteiramente o método. Vamos ver a imagem das quatro disciplinas e depois destrinchar cada uma contra os documentos reais.
As quatro disciplinas como uma bússola: cada ponta é uma regra que, junta, faz um mapa ser confiável — e não apenas lido. Os exemplos nos satélites são todos fatos verificados do repositório.
A grande ideia
Fazer engenharia reversa de um sistema é como ser um cartógrafo entrando num território novo. O mapa que você desenha só serve se quem confiar nele não cair num penhasco que você "supôs" que não existia. As quatro disciplinas existem para que cada linha do mapa seja verificável.
Imagine dois mapas da mesma cidade. O primeiro foi copiado de um folheto turístico antigo: bonito, mas as ruas mudaram. O segundo foi feito andando rua a rua, com cada esquina anotada e um aviso honesto onde o cartógrafo não chegou. Só o segundo é seguro de usar. O método deste curso é o de fazer o segundo mapa: ler a fonte real, gastar profundidade onde importa, citar tudo, e deixar outra pessoa tentar furar suas conclusões.
Pense como… a diferença entre repetir o que o folheto diz e medir a cidade com seus próprios pés. A analogia quebra num ponto: ruas mudam devagar; código mente rápido — um doc de intenção pode estar errado no dia em que foi escrito. Por isso a regra nº 1 não é "às vezes confie no doc", é "o código sempre vence".
O método tem quatro invariantes, e cada uma tem um espelho dentro do próprio motor Alembic que este curso descreve: "o código vence" (a fonte é a verdade), tiers de profundidade (orçamento de atenção declarado), Proof-Gate (o mesmo gate que a lição 17 aplica à execução, virado para dentro da documentação) e builder ≠ validator (a mesma separação do Verifier da lição 18 e do Validator Gate da lição 17). O método não é folclore: é a engenharia do motor aplicada ao ato de documentar o motor.
Estes dois mapas não são teoria: eles existem no repo (docs/alembic-complete-map.md, docs/hermes-complete-map.md) e foi sobre eles que se construiu a matriz de fusão e, em cima dela, um pacote real @alembic/hermes. Se o método falhasse, o pacote teria sido construído sobre mentiras. Por isso o método é o entregável.
Princípio 1 — o código vence, sempre
O próprio cabeçalho do mapa declara a regra. Docs descrevem intenção; intenção deriva. Um mapa que confia no doc acima da fonte herda toda mentira que o doc acumulou:
docs/alembic-complete-map.md — a disciplina, dita logo no topo// "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.: o HANDOFF diz "11 packages / 284 tests"; a árvore tem // 19 packages + 1 app e 415 testes — o mapa reflete a // decomposição, e NOMEIA o drift.
O mapa literalmente registra onde o handoff ficou desatualizado (11 vs 19 pacotes, 284 vs 415 testes) e onde um "bug conhecido" tinha sido de fato corrigido (o contrarian-last, que o HANDOFF.md listava como "ficção a não carregar adiante" mas que a fonte atual já aplica no carregamento do board). Essa honestidade é o entregável — um mapa que silenciasse a divergência seria pior que nenhum mapa.
O mapa e o HANDOFF.md discordam no número de pacotes. Qual destes o método faz?
Reflete o código (19 pacotes + 1 app / 415 testes), e anota a divergência em relação ao handoff (11 / 284). Não faz a média, não omite, não confia no doc. O drift vira uma nota explícita no cabeçalho — porque um leitor que confie no número precisa saber de onde ele veio.
Princípio 2 — tiers de profundidade honestos
Você não consegue ler cada linha de cada arquivo na mesma profundidade — e fingir que leu é a mentira mais comum da engenharia reversa. O método, em vez disso, declara sua profundidade:
No mapa do Alembic isso aparece concreto: a cintura estreita, o funil, o council e o swarm recebem tratamento profundo com citação de linha; a cauda longa (infra, docs, tui, web) recebe um catálogo estruturado (responsabilidade / API / deps / testes / gaps); e dúvidas genuínas são marcadas [uncertain] — por exemplo "[uncertain] whether they live in another package" (drivers de fonte) e "[uncertain] whether any infra tests run under vitest". A fronteira é nomeada, não escondida.
O mesmo orçamento, em faixas: a largura da faixa é a profundidade gasta. Deep-dive para o que sustenta carga, catálogo para a cauda longa, fronteira marcada para o que não se verificou.
ModelAdapter + Result): todo o resto passa por ela. Esse vira deep-dive — leitura linha a linha, com file:line.[uncertain] em vez de adivinhar.[uncertain]. Esse é o orçamento.[uncertain] é suspeito. Ou ele é trivialmente pequeno, ou está mentindo sobre a cobertura. A ausência da fronteira não é um sinal de completude — é um sinal de alerta.Princípio 3 — Proof-Gate em tudo
A nota de método da matriz de fusão é explícita: "Nothing here is decided from memory; every 'Alembic has/lacks X' cites map evidence." Claims são lastreados por artefatos verificáveis — um file:line que você abre, um hit-count que você reproduz com grep, um teste que existe. É a mesma disciplina do Proof Gate que o motor usa (lição 17), virada para dentro da documentação:
- Todo claim não-óbvio cita um caminho e, quando útil, um número de linha — clicável, checável.
- Presença/ausência de capacidade é lastreada em hit-counts sobre o mapa ("
memory=1 hit incidental; sem pacote de memória" ⇒ é um gap genuíno). - Estado verificado vem com o comando que o produziu ("
npx vitest list→ 415 casos").
file:line não é formatação — é o gate de prova da prosa. Sem ela, é ensaio; com ela, é mapa.file:line que abre, um hit-count que se reproduz com grep, ou um teste/comando que existe — algo que um cético pode falsificar em segundos.memory=1 hit incidental; sem pacote de memória" mostra que a ausência é real, não esquecimento. A ausência também é provada.npx vitest list → 415 casos". O leitor pode rodar o mesmo comando e conferir.unit.proof[]: lá, um comando com exit ≠ 0 falha a run; aqui, um claim sem citação não entra no mapa. Em ambos, a regra é "prove na fronteira real, nunca por alegação".Princípio 4 — builder ≠ validator
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 traz "Builder ≠ validator" como regra dura. Um mapa checado só por seu autor herda os pontos cegos do autor; um revisor independente é a versão humana-e-agêntica do Verifier read-only.
| Disciplina | No motor (execução) | Na documentação (este método) |
|---|---|---|
| Fonte da verdade | o código executado, não o plano | o filesystem como construído, não o HANDOFF.md |
| Profundidade declarada | tier de risco por unidade (T1–T4) | deep-dive · catálogo · [uncertain] |
| Prova | Proof Gate: unit.proof[], exit≠0 falha | Proof-Gate da prosa: file:line / hit-count / comando |
| Separação | Verifier read-only ≠ quem construiu | revisor ≠ autor ("Builder ≠ validator") |
Explore as três profundidades
Clique cada tier para ver o que ele exige, com um exemplo real do mapa do Alembic — e veja a faixa correspondente acender no orçamento de profundidade.
A largura da faixa = a profundidade gasta. Note como a fronteira é a mais estreita — e mesmo assim aparece.
Por que isto generaliza
Esses quatro princípios não são do Alembic. Caia em qualquer base de código desconhecida e o método é o mesmo: leia a fonte acima do README quando discordarem — e anote a discordância; orce sua profundidade e declare-a; lastrear todo claim com uma citação que você possa re-checar; e peça a quem não escreveu suas conclusões para tentar furá-las. A disciplina é o que deixa um mapa ser confiável em vez de meramente lido — e foi exatamente o que tornou seguro construir um pacote real @alembic/hermes sobre o mapa do Hermes sem reler antes todas as 30k+ linhas de Python.
delegate_tool.py do Hermes como IGNORE porque o swarm do Alembic já delega melhor. Aquela decisão só foi segura porque o método provou, com evidência citada, o que o Alembic "tem" vs "não tem".Confusões comuns
[uncertain] deixam o mapa parecer incompleto." Eles o deixam honesto. Um mapa sem nenhuma incerteza ou é trivialmente pequeno ou está mentindo sobre sua cobertura. Nomear a fronteira é o que permite ao leitor confiar em tudo que não está marcado.file:line é só formatação." Não — é o Proof-Gate para prosa. Um claim com citação clicável é falsificável em segundos; um claim sem ela é uma asserção a se aceitar por fé. As citações são o que fazem disto um mapa, e não um ensaio.HANDOFF.md dizia "11 pacotes / 284 testes" e listava o contrarian-last como ficção — ambos já desatualizados. O método não pune o doc; ele só registra que a fonte venceu, e onde.Recapitulando
Percorra os quatro princípios como slides — eles são a "bússola" que abriu a lição, agora um a um.
Verifique
Três perguntas. Recupere de memória antes de clicar — é assim que vira retenção.
HANDOFF.md discordam na contagem de pacotes. O que o método faz?[uncertain] na fronteira. a e b são a mentira de cobertura; c esconde os buracos.[uncertain]? Pergunte ao seu professor (este agente) — traga o repo e a gente aloca os tiers juntos.