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: camadas honestas de profundidade, Proof-Gate em tudo, builder ≠ validator, e "o código vence". É a disciplina por trás da fusão, e generaliza para qualquer base de código que você tenha que entender de fora.
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". Esta é a fundação. Documentos de design descrevem intenção; intenção desvia. Um mapa de engenharia reversa que confia no doc acima da fonte herda toda mentira que o doc acumulou:
// docs/alembic-complete-map.md — a disciplina, declarada logo no início // "Este documento 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." // ex.: HANDOFF diz "11 pacotes / 284 testes"; a árvore tem 19 pacotes + 1 app, // 415 testes — o mapa reflete a decomposição, e nomeia o desvio.
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 — um mapa que quietamente disfarçasse a divergência seria pior que nenhum mapa.
Você não consegue ler cada linha de cada arquivo na mesma profundidade — e fingir que conseguiu é a mentira mais comum da engenharia reversa. O método, em vez disso, declara sua profundidade explicitamente:
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", "[uncertain] se algum teste de infra roda sob vitest". A fronteira é nomeada, não escondida.
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." Claims são respaldados por artefatos verificáveis — um file:line que você pode abrir, uma contagem de hits que você pode reproduzir 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:
memory=1 hit incidental; nenhum pacote de memória" ⇒ é um gap genuíno).npx vitest list → 415 casos").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.
Estes quatro princípios não são específicos 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 a declare; respalde todo claim com uma citação que você possa re-checar; e ponha alguém que não escreveu suas conclusões para tentar quebrá-las. A disciplina é o que permite a um mapa ser confiado em vez de meramente lido — e é exatamente o que tornou seguro construir um pacote @alembic/hermes real sobre o mapa do Hermes sem reler todas as 30k+ linhas de Python primeiro.
HANDOFF.md discordam na contagem de pacotes. O que o método faz?[uncertain] na fronteira.[uncertain] fazem o mapa parecer incompleto." Eles o tornam honesto. Um mapa sem marcadores de incerteza é ou trivialmente pequeno ou mentindo sobre sua cobertura. Nomear a fronteira é o que permite ao leitor confiar em tudo o que não está marcado.file:line é só formatação." Não — é o Proof Gate para a prosa. Um claim com citação clicável é um que um cético pode falsificar em segundos; um claim sem ela é uma afirmação a ser aceita por fé. As citações são o que torna isto um mapa e não um ensaio.