Alembic × Hermes · O Curso de Fusão · Visual Course

Alembic × Hermes — o curso de fusão, do motor à linha de código

Ilustração de capa: a fusão Alembic × Hermes — o motor Alembic em camadas (contracts → adapters → harness → clients) recebe os subsistemas reverse-engineered do Hermes (memória, aprendizado, curadoria, clarify, web, skills, mídia) e fecha um loop que se auto-melhora; o arco percorre as 30 lições em 6 módulos.

Trinta lições que ensinam um sistema real: como o motor Alembic é construído, o que foi reverse-engineered do Hermes Agent, quais capacidades foram fundidas (e quais foram deliberadamente ignoradas) e o loop fechado e auto-melhorante que resultou disso — mais a disciplina de ports que segura tudo, uma guerra de engenharia real, um mergulho em cada subsistema @alembic/hermes entregue, uma passagem completa pelo motor em que a fusão se encaixa e, enfim, dois labs práticos, tópicos avançados e um capstone. Cada afirmação aqui vem dos próprios mapas, ADRs e código entregue do projeto. PT-BR.

Começar →Lição 1 · O motor
Fio condutor: uma capacidade do Hermes atravessando a matriz de fusão — descoberta no motor original → veredicto CLONE / ADAPT / MERGE / IGNORE → reimplementação em @alembic/hermes com Result + Zod + ports injetados → gate do Validator → e, no fim, o loop fechado: um run que termina alimenta o próximo (proponha → gate → sedimente). Nada é fundido por opinião; tudo passa pela prova.

Parte 1 · O motor

Lição 1
O motor
O modelo de seis camadas (de contracts L-1 a clients L4), a cintura estreita — um contrato Result que nunca lança — e o funil de distill T0→T3 que vira sources em Learnings.
 Lição 2
Reverse-engineering do Hermes
O que é o Hermes Agent, seu catálogo de ferramentas mapeado uma a uma, e o loop fechado de aprendizado (§1.10) que virou a pedra angular da fusão.
 Lição 3
A matriz de fusão
A decisão CLONE / ADAPT / MERGE / IGNORE para cada capacidade — por que o loop de aprendizado é a pedra angular, por que o cliente MCP fica parked, e por que delegação é IGNORE (o swarm já existe).
 Lição 4
O loop fechado
Memória de snapshot congelado + uma passagem propose→gate-do-Validator→dispose (ADR-0018) + o ciclo de vida do curator. Por que é gated, não auto-aplica (ADR-0006).
 Lição 5
Ports e injeção
FsPort, adapter, Clock e idFactory injetados; Result + Zod + never-throws em cada boundary. Por quê (testabilidade, determinismo, store-agnosticism — ADR-0009) com código real.
 Lição 6
O vazamento de órfãos do Vitest
O incidente (16 workers órfãos, ~1550% CPU), as duas causas, o fix em duas camadas (config endurecida + wrapper que mata o process-group), e como foi verificado.

Parte 2 · Mergulhos profundos

Lição 7
Memória profunda deep dive
O MemoryStore de snapshot congelado: MEMORY.md/USER.md, add/replace/remove por substring única, o delimitador §, limites 2200/1375, e snapshot-vs-live.
 Lição 8
Aprendizado profundo deep dive
reviewAndLearn: propose→gate→apply, o port ReviewGate, scoreThresholdGate(0.7), os buckets applied/rejected/failed e o controle fail-closed.
 Lição 9
Curadoria profunda deep dive
UsageStore + runCurator: o port Clock, active→stale→archived, never-delete, os gates pinned/agent-only e o anchor never-active +Infinity.
 Lição 10
Clarificação profunda deep dive
ClarifyGateway, o gate humano T4: Promise + registry de resolvers + timeout, monotonicIdFactory, Zod com validação cross-field e a regra leave-pending.
 Lição 11
Web profunda deep dive
webSearch / webExtract: os ports WebBackend + Compressor, createFetchBackend sobre o fetch global (sem dep), o clamp maxResults e defesa em profundidade.
 Lição 12
Skills profundas deep dive
SkillStore, progressive disclosure: list=metadata / view=body, CRUD, path-safety e o parser de frontmatter escalar sem dependências.
 Lição 13
Mídia profunda deep dive
transcribe / analyzeImage: os ports TranscriptionBackend/VisionBackend, fetch backends, Zod no boundary e por que o caminho de ML local é IGNORE.

Parte 3 · A arquitetura

Lição 14
A cintura estreita engine
ModelRunResult discriminado em ok (nunca lança), e runWithGuards — Zod-in → try/catch → circuit-breaker → retry → rede de segurança externa.
 Lição 15
O funil engine
O ETL de 4 tiers (T0 $0 → T1 ~$0 → T2 metered → T3 council+verifier), o gate verified-GO e as três invariantes de segurança (PII, budget, append-only).
 Lição 16
As quatro invariantes engine
run-never-throws · adapter/store-agnostic · IDs content-addressed & run-dir determinístico · dissenso preservado pelo Verifier. Quatro, não seis.
 Lição 17
O pipeline de gates engine
Scope → Council → Proof → Validator → Publish, cada um fail-closed — e onde o ReviewGate do loop de aprendizado se encaixa na mesma família.
 Lição 18
Council e verifier engine
DebateEngine (fases seriais / membros paralelos), score 0–10, o Verifier maker-checker read-only e o painel N-lens como gate de emissão T3+.
 Lição 19
O swarm engine
orchestrator → lead → worker, fila gated por dependência, depth-bound (MAX_DEPTH=2), isolamento por git-worktree, park T4, resume crash-safe.

Parte 4 · Método e labs

Lição 20
O método de reverse-engineering method
Como os dois mapas foram construídos: o código vence, tiers de profundidade honestos, Proof-Gate em tudo, builder ≠ validator. A disciplina por trás da fusão.
 Lição 21
O framework de fusão method
CLONE / ADAPT / MERGE / IGNORE de ponta a ponta — duas perguntas, um 2×2 e quatro veredictos trabalhados (loop de aprendizado, MCP, delegate, neutts).
 Lição 22
Lab: construir um subsistema lab
Mão na massa: escreva um NoteStore do zero — FsPort injetado, Zod no boundary, Result + never-throws, bounded — espelhando como memory/skills foram feitos. Com um "agora você".
 Lição 23
Lab: o passo de aprendizado lab
Mão na massa: monte reviewAndLearn a partir de três ports injetados (proposer + ReviewGate + MemoryStore); veja um turno se dividir em applied/rejected/failed e force cada bucket.

Parte 5 · Engenharia

Lição 24
A trilha de ADRs advanced
As decisões que moldaram a fusão: ADR-0001 (motor, não produto), 0005 (gate humano), 0006 (gate de emissão do validator), 0009 (cintura estreita), 0018 (o loop gated) — e como se restringem.
 Lição 25
Engenharia de test-safety advanced
Fundo do fix do vitest-orphan: process groups, detached:true, kill(-pgid), o wrapper safe-test.mjs, o vitest.config.ts endurecido e o sweep pós-run. Estende a Lição 06.
 Lição 26
Proveniência e segurança advanced
ADR-0011: redação de PII antes do egress, fail-closed em tudo, o guard de path-traversal, Zod no boundary, isolamento CL4R1T4S e proveniência content-addressed.
 Lição 27
Tiers, custo e orçamento advanced
A escada de Tiers T0–T4 + o marcador LOCAL, o registry de 11 modelos, pickCheapestForTier e o BudgetGuard fail-closed onde cap não-positivo significa só free-tier.
 Lição 28
Determinismo e replay advanced
IDs de run content-addressed (runIdFor), o run-dir determinístico, o ban da plan-VM a Date.now()/Math.random() e o seam Clock/id-factory injetado que mantém o replay honesto.
 Lição 29
Estendendo a fusão advanced
A receita: como adicionar um novo subsistema @alembic/hermes — ports-and-injection, Result+Zod, sem dep nova, vitest.config.ts por pacote, test:safe. Um checklist para o próximo agente.

Parte 6 · Capstone

Lição 30
Capstone: a máquina inteira capstone
O quadro completo: o loop distill→learn→sediment→prune, o que foi entregue (7 subsistemas, ~565 testes), a fronteira parked (cliente MCP, corpus, design/GTM) e um quiz transversal de fechamento.