Lab: o passo de aprendizado

export const reviewAndLearn = async (
  summary: string,
  deps: ReviewDeps,
): Promise<Result<LearnOutcome, Error>> => { /* … */ };

O passo de aprendizado: propor → gate → aplicar, e a saída sempre se separa em três baldes nomeados.

O driver reviewAndLearn(summary, deps) depende só de ports injetados. Seu ReviewDeps tem exatamente três campos — e os três são obrigatórios:

Antes de codar, fixe o mapa mental. Um resumo de turno entra; cada proposta segue um caminho; a saída sempre cai num de três baldes — ou o passo inteiro aborta com err.

O MemoryStore real do @alembic/hermes precisa de um FsPort. Reusamos o mesmo fake Map-backed do Lab 1, e então chamamos load() uma vez para inicializar o estado vivo.

import {
  MemoryStore, reviewAndLearn, scoreThresholdGate,
} from '@alembic/hermes';
import { ok, err } from '@alembic/contracts';
import type { ReviewProposal, ReviewProposer } from '@alembic/hermes';

const memory = new MemoryStore(makeFakeFs(), '/agent');  // FsPort falso do Lab 1
await memory.load();                                      // inicializa o estado vivo

• Importei MemoryStore, reviewAndLearn e scoreThresholdGate de @alembic/hermes.
• Construí o store com o FsPort falso e chamei await memory.load().

const fakeProposer: ReviewProposer = async (_summary) => {
  const proposals: ReviewProposal[] = [
    { target: 'memory', op: { action: 'add', content: 'Build roda offline por padrão' },
      rationale: 'observado neste run', score: 0.9 },   // forte → deve APLICAR
    { target: 'memory', op: { action: 'add', content: 'talvez preferir tabs?' },
      rationale: 'palpite', score: 0.4 },                // fraco → deve REJEITAR
  ];
  return ok(proposals);
};

export const reviewProposalSchema = z.object({
  target: memoryTargetSchema,                  // 'memory' | 'user'
  op: memoryOpSchema,                          // add | replace | remove
  rationale: z.string(),
  score: z.number().min(0).max(1),         // fora de [0,1] → err
});

Agora monte os três ports e rode um passo. O gate padrão aprova score ≥ 0.7, então a proposta 0.9 é aplicada e a 0.4 é rejeitada.

const result = await reviewAndLearn('terminei uma unidade; testes verdes', {
  proposer: fakeProposer,
  gate: scoreThresholdGate(0.7),   // o padrão conservador do pacote
  memory,
});

if (result.ok) {
  console.log(result.value.applied.length);   // 1  (a proposta 0.9)
  console.log(result.value.rejected.length);  // 1  (a proposta 0.4)
  console.log(result.value.failed.length);    // 0
  console.log(memory.entries('memory'));     // ['Build roda offline por padrão']
}

O store agora guarda exatamente a escrita aprovada. A proposta rejeitada carrega a razão do gate — "score 0.4 < threshold 0.7 (learn only from validated wins)" — então nada é descartado em silêncio.

A distinção sutil: rejected = o gate disse não; failed = o gate disse sim, mas o store não conseguiu escrever (por exemplo, estourou o orçamento de caracteres). Para vê-lo, encolha o limite do store de modo que uma escrita aprovada transborde. O passo ainda tem sucesso no geral — só aquela escrita cai em failed:

const tiny = new MemoryStore(makeFakeFs(), '/agent', { memoryCharLimit: 12 });
await tiny.load();

const r = await reviewAndLearn('turno', {
  proposer: async () => ok([{ target: 'memory',
    op: { action: 'add', content: 'uma frase bem mais longa que doze caracteres' },
    rationale: 'x', score: 0.95 }]),   // o gate APROVA (0.95 ≥ 0.7)…
  gate: scoreThresholdGate(),
  memory: tiny,
});
// …mas o store recusa a escrita acima do orçamento:
// r.value.applied = []   r.value.rejected = []
// r.value.failed  = [{ proposal, reason: '…would exceed the limit…' }]

Três coisas abortam o passo inteiro com err (e não num balde): um erro do proposer, um erro do gate, e uma proposta com forma inválida (o Zod recusa). Tente um proposer que devolve err:

const bad = await reviewAndLearn('turno', {
  proposer: async () => err(new Error('modelo deu timeout')),
  gate: scoreThresholdGate(),
  memory,
});
// bad.ok === false — o passo inteiro falhou fechado; o store fica intacto.

const proposed = await deps.proposer(summary);
if (!proposed.ok) return proposed;            // proposer erra → aborta
if (proposed.value.length === 0) return ok(emptyOutcome());

// dentro de processOne, por proposta:
if (!parsed.success) return err(/* forma inválida */);
const verdict = await deps.gate(proposal);
if (!verdict.ok) return verdict;                // gate erra → aborta
if (!verdict.value.approved) { acc.rejected.push(…); return; }
const written = await deps.memory.apply(…);
if (!written.ok) { acc.failed.push(…); return; }  // store recusa → failed, NÃO aborta
acc.applied.push(proposal);

E um resumo vazio ou zero propostas é um no-op válido — ok com os três baldes vazios, espelhando o "Nothing to save." da fonte. (Um resumo só com espaços faz o driver retornar antes mesmo de chamar o proposer.)

Mexa nos controles e veja em qual balde a proposta cai. Replica a lógica exata do driver: o gate compara score ao piso (inclusivo); se aprovar, o store tenta escrever; se o conteúdo passar do memoryCharLimit, a escrita vai para failed.

Vamos rodar, no papel, um único passo com quatro propostas e um store de orçamento apertado. Acompanhe cada proposta até seu balde.

Clique para virar. Recupere a resposta de cabeça antes de conferir.

Os cinco pontos do lab, em sequência. Use ← → ou os botões.

Os três baldes (resultado normal) versus o caminho err (aborto fail-closed) — cada um pede um conserto diferente.