Aprendizado profundo: reviewAndLearn

O fluxo tem três estágios e três destinos. Cada proposta percorre os estágios e cai em um de três baldes de resultado. Veja o desenho inteiro antes do código:

O caminho de uma proposta: do proposer ao gate, e do gate para um dos três baldes. Erro de infraestrutura para o passo; recusa de política apenas registra e continua.

O driver é pequeno e total. Um resumo vazio ou zero propostas curto-circuita para um resultado vazio (um passo no-op é válido); um erro do proposer ou do gate faz o passo inteiro falhar fechado:

// packages/hermes/src/learning/review.ts — reviewAndLearn
export const reviewAndLearn = async (
  summary: string, deps: ReviewDeps,
): Promise<Result<LearnOutcome, Error>> => {
  if (summary.trim().length === 0) return ok(emptyOutcome());
  const proposed = await deps.proposer(summary);
  if (!proposed.ok) return proposed;                // erro do proposer ⇒ falha fechado
  if (proposed.value.length === 0) return ok(emptyOutcome());
  const acc: OutcomeAcc = { applied: [], rejected: [], failed: [] };
  for (const raw of proposed.value) {
    const stepErr = await processOne(raw, deps, acc);
    if (stepErr) return stepErr;                    // erro do gate / forma ruim ⇒ falha fechado
  }
  return ok({ applied: acc.applied, rejected: acc.rejected, failed: acc.failed });
};

Trecho citado verbatim de review.ts. Note os dois return que saem cedo: resumo vazio e zero propostas.

O resultado separa três destinos. A distinção entre rejected (o gate disse não) e failed (o gate disse sim, mas o store não conseguiu gravar) é load-bearing para observabilidade — uma escrita estourada de orçamento nunca pode ser confundida com uma recusa de política:

// packages/hermes/src/learning/review.ts — processOne
const parsed = reviewProposalSchema.safeParse(raw);   // saída de modelo não confiável
if (!parsed.success) return err(new Error(`Invalid review proposal: …`));
const proposal = parsed.data;
const verdict = await deps.gate(proposal);
if (!verdict.ok) return verdict;                      // ERRO do gate ⇒ derruba o passo
if (!verdict.value.approved) {
  acc.rejected.push({ proposal, reason: verdict.value.reason }); // gate disse NÃO
  return undefined;                                 // continua o passo
}
const written = await deps.memory.apply(proposal.target, proposal.op);
if (!written.ok) {
  acc.failed.push({ proposal, reason: written.error.message }); // store disse NÃO
  return undefined;                                 // ainda continua
}
acc.applied.push(proposal);

A tabela dos três fins

Explore: para onde vai cada proposta?

Um lote inteiro, em uma imagem

Cinco propostas entram juntas. Nenhuma rejeição nem falha de store derruba o lote — cada uma só cai no seu balde, e reviewAndLearn devolve ok com a contagem dos três:

Até o Validator Gate real do @alembic/coda (ADR-0006) plugar o seu próprio ReviewGate, o padrão conservador aprova uma proposta se e somente se score ≥ 0,7 — a codificação mecânica de "aprender só de vitórias validadas", herdada do hermes-mini-loop:

// packages/hermes/src/learning/gate.ts — scoreThresholdGate
export const scoreThresholdGate = (
  min: number = DEFAULT_REVIEW_SCORE_THRESHOLD,   // 0.7
): ReviewGate => {
  return async (proposal) => {
    const approved = proposal.score >= min;        // fronteira INCLUSIVA
    const reason = approved
      ? `score ${proposal.score} ≥ threshold ${min}`
      : `score ${proposal.score} < threshold ${min} (learn only from validated wins)`;
    return ok({ approved, reason });               // puro & total: sempre ok(verdict)
  };
};

Brinque com o piso

À esquerda do piso, reprova; em 0,70 exato, aprova (a fronteira é inclusiva).

Esta é a sutileza que vale internalizar. O gate devolve ok({approved:false, …}) para uma reprovação — não err. O invólucro Result sinaliza se o gate funcionou; o verdict.approved carrega a decisão. Um gate que deu erro (ex.: o serviço do Validator caiu) devolve err e para o passo.

Duas camadas de sinal. O Result diz se a máquina rodou; o verdict diz o que ela decidiu. Só se lê o veredito quando o Result é ok.

return ok({
  approved: false,
  reason: 'score 0.55 < 0.7'
});
// → rejected[], passo segue

return err(
  new Error('Validator offline')
);
// → passo PARA fechado

O laço não tem lógica de dedup própria. Escritas aprovadas fluem pelo dedup que já existe no MemoryStore — repropor uma entrada que já está lá é um no-op de sucesso (então conta como applied, mas o store continua com uma entrada). Isso espelha a intenção do ON CONFLICT DO UPDATE do mini-loop: reforçar, não empilhar duplicatas.

Verdadeiro ou falso (responda mentalmente)

Simples ↔ Técnico: a mesma ideia, duas alturas

A prova desta lição não é a leitura — é a suíte. O arquivo review.test.ts tem 14 casos que fixam cada afirmação feita aqui: a fronteira 0,69/0,70, failed vs rejected, reforçar-não-duplicar e o fail-closed em erros de proposer/gate. Rode os testes do pacote:

# a prova do passo de aprendizado, isolada
pnpm --filter @alembic/hermes test

# a baseline completa do monorepo
pnpm -r typecheck && pnpm -r build && pnpm -w test

As fontes (todas no repo, lidas verbatim)