Lab: o passe de aprendizado

No Lab 1 você construiu um store. Agora você liga a pedra angular da fusão (Lições 4 e 8): um passe fechado de auto-aperfeiçoamento onde um revisor propõe gravações duráveis, um gate dispõe, e gravações aprovadas sedimentam no store. Você vai montar reviewAndLearn a partir de três portas injetadas — um proposer fake, um ReviewGate e o MemoryStore real da família do Lab 1 — e ver um turno se dividir nos baldes applied / rejected / failed. Esta é a API real entregue; você a chama exatamente como a produção faz.

01 · Propõe · dispõe · sedimenta — a forma do passe

Antes do código, a forma. Pense num diário de bordo guardado por um editor cauteloso. Ao fim de cada turno, um revisor rabisca o que valeria a pena lembrar (propõe). Um editor lê cada rabisco e decide se entra no diário (dispõe). Só então o que passou é escrito em tinta no diário durável (sedimenta). Nada vira tinta sem passar pelo editor — e essa é exatamente a regra de ADR-0018.

A mesma forma, vista como quem toca o quê: o revisor só escreve em rascunho; o editor é o único portão para a tinta; o diário durável só recebe o que o editor liberou. Essa separação é literal no código — reviewAndLearn chama deps.memory.apply(...) apenas depois de verdict.value.approved ser verdadeiro (review.ts:90-101).

02 · As três portas que você liga juntas

O driver reviewAndLearn(summary, deps) depende somente de portas injetadas — sem adapter concreto, sem construção concreta de store (ADR-0009). Suas ReviewDeps são três campos, e todos os três são obrigatórios (review.ts:30-37):

03 · Passo 1 — construa o store (reuse a família do Lab 1)

// setup

O MemoryStore real do @alembic/hermes precisa de um FsPort. Reusamos o mesmo fake apoiado em Map do Lab 1, depois fazemos load() uma vez para inicializar seu estado vivo.

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

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

04 · Passo 2 — escreva um proposer fake

Em produção o proposer envolve uma chamada de modelo e traduz seu ModelRunResult num Result. No lab ele só retorna propostas fixas. Cada proposta é um { target, op, rationale, score } — o score ∈ [0,1] é a própria confiança do revisor, e o gate decide se ela passa do piso (types.ts:62-71).

const fakeProposer: ReviewProposer = async (_summary) => {
  const proposals: ReviewProposal[] = [
    { target: 'memory', op: { action: 'add', content: 'Build runs offline by default' },
      rationale: 'observed this run', score: 0.9 },   // forte → deve APLICAR
    { target: 'memory', op: { action: 'add', content: 'maybe prefer tabs?' },
      rationale: 'hunch', score: 0.4 },                // fraco → deve REJEITAR
  ];
  return ok(proposals);
};

05 · Passo 3 — rode o passe e leia os baldes

// a chamada

Agora monte as três portas e rode um passe. O gate default aprova score ≥ 0.7 (a fronteira é inclusiva, gate.ts:30), então a proposta 0.9 aplica e a 0.4 é rejeitada.

const result = await reviewAndLearn('finished a unit; tests green', {
  proposer: fakeProposer,
  gate: scoreThresholdGate(0.7),   // o default conservador entregue
  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 runs offline by default']
}

O store agora contém exatamente a gravação 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 (gate.ts:32-33).

06 · Passo 4 — force cada balde, na mão (worked → agora você)

Você viu o passe rodar feliz. Agora force cada um dos três destinos de propósito — é a melhor forma de entender a diferença entre eles. Siga os passos; o último exercício é seu.

Os três baldes não são aleatórios: cada um é o cruzamento de duas decisões binárias — o gate olha o score, e (só se aprovar) o store olha o tamanho. Esta matriz mostra os quatro quadrantes e em que balde cada combinação cai:

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

const r = await reviewAndLearn('turn', {
  proposer: async () => ok([{ target: 'memory',
    op: { action: 'add', content: 'a sentence far longer than ten chars' },
    rationale: 'x', score: 0.95 }]),   // gate APROVA (0.95 ≥ 0.7)…
  gate: scoreThresholdGate(),
  memory: tiny,
});
// …mas o store rejeita a gravação acima do orçamento:
// r.value.applied = []  r.value.rejected = []  r.value.failed = [{proposal, reason:'…would exceed the limit…'}]

07 · Simulador: force cada balde ao vivo

Agora torne tátil o que você fez na mão. Mexa os três controles — o score da proposta, o tamanho do conteúdo e o orçamento do MemoryStore — e o passe é avaliado exatamente como reviewAndLearn faz: o gate compara score com o piso 0.7; se aprovar, o store compara o tamanho com o orçamento. O balde de destino acende.

08 · Por que failed não é rejected

A distinção sutil que o simulador deixa óbvia: rejected = o gate disse não; failed = o gate disse sim mas o store não conseguiu gravar (ex.: acima do orçamento de chars). Colapsar um no outro mentiria para o operador.

Repare onde cada desfecho se separa na mesma linha do tempo de uma proposta: rejected sai cedo (no gate); failed só se decide um passo depois (no store); e applied percorre os dois. É a ordem exata de processOne (review.ts:90-101):

09 · Passo 5 — os caminhos fail-closed

Há um terceiro tipo de desfecho, acima dos baldes: o passe inteiro abortar com err. Duas coisas o causam — um erro do proposer e um erro do gate. Não são baldes: são curto-circuito. Experimente um proposer que retorna err:

const bad = await reviewAndLearn('turn', {
  proposer: async () => err(new Error('model timed out')),
  gate: scoreThresholdGate(),
  memory,
});
// bad.ok === false — o passe inteiro falhou fechado; o store fica intocado.

No código, isso é uma linha: if (!proposed.ok) return proposed (review.ts:61) — um erro do proposer faz short-circuit antes de qualquer gate ou gravação. O mesmo vale para o gate: if (!verdict.ok) return verdict (review.ts:90). E um summary vazio ou zero propostas é um no-op válido — ok com três baldes vazios, espelhando o "Nothing to save." da fonte (review.ts:58, 62).

10 · rejected vs failed vs err — lado a lado

Toda a lição gira em torno de três desfechos que parecem "não gravou" mas são fundamentalmente diferentes. Veja-os explícitos, na mesma tabela: o que os causa, onde a proposta pousa, e o que acontece com o resto do passe.

A coluna que mais separa os quatro desfechos é a última: o passe continua? Três deles são apenas baldes dentro de um ok — o passe segue inteiro. Só o err é diferente em espécie: ele é o Result externo virando { ok: false } e curto-circuitando tudo. Veja a fronteira:

11 · Como isso se encaixa

Você acabou de construir reviewAndLearn ligando suas três portas à mão. Afaste a câmera: o que você montou neste lab é o loop fechado em miniatura. As mesmas três portas — proposer → gate → memory — são o último elo da esteira real do motor: a run de hoje só deixa marca durável para a run de amanhã passando por aqui, e só depois que todos os gates passaram. No lab elas são fakes; em produção, o proposer é um ModelAdapter, o gate é o Validador do @alembic/coda e o memory é o store persistido no run-dir. A forma que você ligou não muda — é a invariante de injeção (ADR-0009) que torna o seu passe de brinquedo idêntico, em estrutura, ao de produção.

Onde você está na metodologia. O motor do Alembic é um loop: aprender → analisar → executar uma unidade → verificar na fronteira real → decidir, e então recomeçar com o que se aprendeu. O passe que você reconstruiu neste lab é a peça que torna esse “recomeçar com o que se aprendeu” literal e seguro: sem ele, cada run começaria do zero; com ele — e só com o gate no caminho — a memória cresce apenas com vitórias validadas. Para ver a esteira inteira em movimento e clicar nesta etapa no mapa, abra o mapa interativo da metodologia.

• Lição 08 · reviewAndLearn (a teoria) — é a peça que este lab reconstrói; lá você leu por dentro o passe gated, aqui você o liga das três portas com a própria mão.
• Lição 04 · O loop fechado — é o ciclo que contém este passe; o que você montou é o último elo (“decidir → recomeçar com o aprendido”) que fecha o loop.
• Lição 07 · MemoryStore — é o store que você injetou como terceira porta; o passe não tem dedup próprio, reusa o do store (a seção 10 da Lição 08 mostra “reforçar, não duplicar”).
• Lição 22 · Lab: um subsistema — é o lab irmão; lá você constrói um subsistema do zero pela mesma disciplina de portas injetadas + testes que dirige este passe.

12 · Na prática

Você montou o passe das três portas e forçou cada balde na mão. Agora rode o mesmo passe pela CLI real, ponta a ponta — é o mesmo reviewAndLearn que você acabou de construir, só que dirigido pela alembic run em vez de um teste. O aprendizado é opt-in: uma run normal não aprende. A flag --learn liga o passe gated (é real — apps/cli/src/args.ts:189, default OFF, ADR-0018), e --offline roda tudo hermético ($0, sem rede). Nesse modo o proposer é o adapter offline determinístico e o gate é o Validador — exatamente as portas do lab, agora de verdade:

# liga o passe gated (ADR-0018) ao fim de uma run, hermético e $0
alembic run --goal GOAL.md --plan alembic.plan.ts --learn --offline --yes

# … a run executa as unidades e passa pelos gates (Proof + Validador) …
# então, SÓ porque --learn está ligado, vem a última linha do passe:
#   learning gate: 2 applied, 1 rejected

Dois detalhes que amarram direto com o que você construiu. Primeiro: sem a flag, nada acontece — o aprendizado é aditivo e desligado por padrão, então uma run verde continua verde (commands.ts:1364, if (args.learn)). Segundo: se não houver adapter de proposer disponível, o passe é pulado (log run:learning-pass-skipped, commands.ts:1367), nunca quebra a run — é a mesma postura fail-closed da seção 09 aplicada ao próprio gatilho.

Quer ir além do resumo de uma linha? O passe inteiro que você reconstruiu também é exercitado pelos testes do kernel — pnpm --filter @alembic/hermes test roda os casos do review.test.ts (a fronteira 0.69/0.70, failed vs rejected, fail-closed nos erros de proposer/gate) que este lab destilou. É a prova de que o comportamento que você montou na mão é o comportamento que roda.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.

Sua vez — estenda o passe