A trilha de ADRs: as decisões que moldaram a fusão

Por baixo do capô

O repo mantém os ADRs em docs/adr/; dezoito estão aceitos. São append-only: uma decisão posterior supersede uma anterior (com seu próprio registro datado), nunca a edita — então a trilha é uma história verdadeira, não um retrato "arrumado". Cinco deles formam a espinha de toda a fusão @alembic/hermes: 0001, 0005, 0006, 0009 e 0018.

A propriedade que faz a trilha valer ouro: cada ADR registra também as opções consideradas e rejeitadas. Em 0009, por exemplo, a opção rejeitada é nomeada — "conventional throwing clients (exceptions on error / 429 / timeout)". Gravar o caminho rejeitado é o que transforma a decisão em restrição executável, não em mera informação.

O texto, e o que ele força

Por isso a fusão portou ferramentas como bibliotecas (um MemoryStore, uma função webSearch) e nunca um app de agente executável com UI. O ADR também deixa uma porta aberta: "If there is real market pull, productizing Alembic as harness-as-a-service … may become a new decision" — registrada como um ADR futuro que supersede o escopo deste, nunca uma edição.

A opção rejeitada e a consequência que carrega tudo

A opção rejeitada é nomeada — "conventional throwing clients" — porque elas "espalham try/catch pela orquestração … e acoplam quem chama a formatos de erro específicos do provedor". A parte que sustenta o resto: retry, circuit-breaking, medição de orçamento e quórum do council "todos operam sobre resultados tipados uniformes". Essa uniformidade é exatamente por que todo subsistema do hermes pôde adotar o mesmo formato Result sem casos especiais.

// a cintura: a forma que todo subsistema do hermes fala
type ModelRunResult =
  | { ok: true;  value: … }
  | { ok: false; error: { code; message; retryable } }

// run() NUNCA lança — a falha é um valor, não uma exceção
const r = await adapter.run(input)
if (!r.ok) { /* trate o err como dado, sem try/catch */ }

De "barato e profundo" a "nada emite sem gate"

O ADR decide que o roteador vira cheapest-above-depth-floor: pickCheapestForTier ganha uma restrição de piso de qualidade em vez de pegar o modelo mais barato direto. Para a fusão, a leitura load-bearing é outra: a proposta de um revisor não é verdade, é um candidato, e um gate decide. O default scoreThresholdGate(0.7) é a codificação conservadora desse piso até o Validator real do @alembic/coda ser ligado.

Reversibilidade decide, não a etapa

Por isso ship e gasto real defaultam para T4-park (fail-closed), enquanto "Distillation (T0–T3 → Signal/Learning) e discover→build são HITL-free". Esse é o princípio que o ClarifyGateway implementa: uma pergunta estruturada e bloqueante é a superfície humana T4, usada só onde a reversibilidade acaba. As duas opções rejeitadas estão nomeadas no ADR: "gate before build" (reintroduz humano em trabalho reversível) e "fully autonomous through ship" (expõe dinheiro e reputação a um erro não supervisionado).

As quatro garantias, e por que a forma é forçada

Leia os dois itens acima e você vê a trilha funcionando como sistema: 0018 não pode simplesmente clonar o Hermes porque 0006 proíbe emissão sem gate e 0009 proíbe lançar exceção — então a única forma que sobra é exatamente o propose→gate→apply sobre portas injetadas que você construiu no Lab 2 (lição 23). O ADR ainda nomeia as quatro garantias: (1) só portas injetadas; (2) Validator-gated, não auto-aplicado; (3) default conservador scoreThresholdGate(0.7) com gate mais rico opt-in; (4) o passo é fail-closed, com Zod na fronteira porque, em produção, é saída de modelo não-confiável.

// 0018: a forma que 0006 + 0009 deixam como única possível
reviewAndLearn(summary, { proposer, gate, memory })
  // proposer (1 chamada ModelAdapter) → ReviewProposal[]
  // gate dispõe: scoreThresholdGate(0.7) aprova score ≥ 0.7
  // aprovados aplicam ao MemoryStore (reusa dedup: reforça, não duplica)
  // erro de proposer/gate → err (fail-closed); empty summary → no-op