Lab: construa um subsistema

Hora de construir, não só ler. Neste lab você escreve um pequeno NoteStore do zero — um store limitado, persistido em arquivo, com um FsPort injetado, validado na fronteira com Zod, que retorna Result<T, Error> e nunca lança exceção. É o mesmo esqueleto sobre o qual o MemoryStore e o SkillStore entregues foram construídos (lições 5, 7, 12), reduzido à menor coisa que ainda justifica o padrão. No final você terá escrito todas as camadas que o motor exige de um subsistema — e um exercício "sua vez" o estende.

01 · O alvo: um store com quatro propriedades

As "Regras para mudanças seguras" do motor (CLAUDE.md) dizem que um subsistema deve ser mínimo, testável e fail-closed. Antes de escrever uma linha, fixe o alvo: o NoteStore deve ter as quatro propriedades que todo subsistema entregue tem. Pense nelas como uma analogia simples — um cofre de recados:

02 · O esqueleto de ports (a forma antes do código)

Antes dos passos, veja a forma do subsistema — quem depende de quem. O segredo está numa única seta: a classe aponta para a interface FsPort, não para o node:fs. Quem fornece o fs de verdade é quem constrói o store (produção ou teste). Esse é o esqueleto de ports-e-injeção:

A interface FsPort (de packages/etl/src/fs-port.ts:61) é maior do que o NoteStore precisa. Você só consome cinco dos seus métodos; o resto (readDir, appendLine, openLineStream) você nem importa. Depender de uma interface deixa isso explícito — você usa só a fatia que precisa, e o fake de teste só precisa implementar essa fatia:

E aqui está o pagamento da injeção, lado a lado: o mesmo corpo de classe recebe a porta de produção ou o fake de teste — só muda o argumento do construtor. A classe não tem um if (test), não conhece qual recebeu; é por isso que o teste exercita o caminho real:

03 · Os seis passos de construção

Construir o subsistema é um processo de seis passos, sempre na mesma ordem: do contrato de entrada até a prova. Veja o mapa antes de codar — cada caixa é um arquivo/bloco que você vai escrever na seção 04:

04 · Construa, passo a passo (depois é a sua vez)

Agora escreva o subsistema, um passo de cada vez. Cada passo abaixo traz o código real (compila contra o workspace) e o porquê. No fim, um passo é seu. Recuperar o procedimento — não só ver o resultado pronto — é o que fixa o padrão.

// Uma nota é uma string não-vazia, trimada, com menos de 280 chars.
import { z } from 'zod';

export const noteSchema = z.string().trim().min(1).max(280);
export type Note = z.infer<typeof noteSchema>;

import { ok, err, tryCatchAsync, type Result } from '@alembic/contracts';
import type { FsPort } from '@alembic/etl';
import { noteSchema } from './schema.js';

export const DEFAULT_MAX_NOTES = 50;
const FILENAME = 'NOTES.md';
const DELIMITER = '\n---\n';

export interface NoteOutcome {
  readonly message: string;
  readonly count: number;   // contagem viva de entradas após a gravação
  readonly max: number;
}

export class NoteStore {
  private entries: string[] = [];

  constructor(
    private readonly fs: FsPort,      // ← injetado. sem `import fs`.
    private readonly baseDir: string,
    private readonly max: number = DEFAULT_MAX_NOTES,
  ) {}

  private path(): string {
    return this.fs.joinPath(this.baseDir, FILENAME);
  }

  async load(): Promise<Result<void, Error>> {
    const ensured = await tryCatchAsync(() => this.fs.ensureDir(this.baseDir));
    if (!ensured.ok) return ensured;          // short-circuit em falha de IO

    const meta = await tryCatchAsync(() => this.fs.stat(this.path()));
    if (!meta.ok) return meta;
    if (!meta.value) { this.entries = []; return ok(undefined); }  // sem arquivo ⇒ vazio

    const read = await tryCatchAsync(() => this.fs.readText(this.path()));
    if (!read.ok) return read;
    this.entries = read.value.split(DELIMITER).map((s) => s.trim()).filter(Boolean);
    return ok(undefined);
  }

  async add(input: unknown): Promise<Result<NoteOutcome, Error>> {
    const parsed = noteSchema.safeParse(input);            // ① Zod na fronteira
    if (!parsed.success) return err(new Error(`Invalid note: ${parsed.error.message}`));
    const note = parsed.data;

    if (this.entries.includes(note)) {                     // ② dedup (sucesso no-op)
      return ok({ message: 'exists', count: this.entries.length, max: this.max });
    }
    if (this.entries.length >= this.max) {                  // ③ limita ANTES de gravar
      return err(new Error(`At capacity (${this.max}). Remove a note first.`));
    }

    this.entries.push(note);                                // ④ muta, depois persiste
    const saved = await tryCatchAsync(() =>
      this.fs.writeFileAtomic(this.path(), this.entries.join(DELIMITER)));
    if (!saved.ok) { this.entries.pop(); return saved; }   // rollback em falha de IO
    return ok({ message: 'added', count: this.entries.length, max: this.max });
  }

  list(): readonly string[] { return this.entries; }
}

Vale isolar o passo 4 num diagrama, porque ele esconde uma sutileza fail-closed: um arquivo ausente não é um erro. O load() checa stat antes de ler — se o arquivo não existe, o store é simplesmente vazio (ok), não um err. Só um IO que de fato falha (permissão, decode) vira err. Siga as três chamadas pela porta:

05 · Dentro do add(): as quatro guardas em ordem

O add() parece simples, mas cada linha tem um motivo. Pense nele como uma esteira de inspeção: a nota passa por quatro postos, em ordem, e qualquer reprovação a tira da esteira com um err — só quem passa nos quatro chega ao disco. Veja a esteira:

Quer o porquê em duas profundidades? Alterne abaixo entre a explicação simples e a técnica:

O posto ④ depende de uma peça que merece um desenho próprio: o tryCatchAsync. Ele é a ponte entre dois mundos — o mundo do node:fs, que lança exceções, e o mundo do Result, onde falha é um valor. Sem essa ponte, um ENOENT escaparia como exceção e quebraria a promessa "nunca lança" da assinatura:

E o ramo de falha do posto ④ esconde a decisão mais sutil do lab: o pop() de rollback. Veja-o como uma linha do tempo de duas trilhas — memória e disco — durante um add() cuja gravação falha. Sem o pop(), as trilhas divergem para sempre; com ele, voltam a coincidir antes do err sair:

06 · O caminho de uma chamada (fluxograma de decisão)

Agora siga uma única chamada add() através das decisões, do começo ao fim. Cada losango é uma pergunta que escolhe o caminho; só um caminho chega ao ok({message:'added'}). Repare em quantas saídas são err ou ok — e que nenhuma é uma exceção:

07 · Prove com um FsPort fake (passo 6)

Como o IO é injetado, o teste não precisa de diretório temporário nem disco real — um fake apoiado em Map satisfaz a porta. É o invariante 2 rendendo diretamente: o mesmo código é exercitado em memória.

// notes/note-store.test.ts — o fake tem ~10 linhas
const makeFakeFs = (): FsPort => {
  const store = new Map<string, string>();
  return {
    joinPath: (...p) => p.join('/'),
    stat: async (p) => (store.has(p) ? { size: 0, mtimeMs: 0, isFile: true, isDirectory: false } : undefined),
    readText: async (p) => store.get(p) ?? '',
    writeFileAtomic: async (p, c) => { store.set(p, c); },
    ensureDir: async () => {},
    // readDir / appendLine / openLineStream: não usados aqui — stub conforme necessário
  } as FsPort;
};

it('rejects an empty note and never throws', async () => {
  const s = new NoteStore(makeFakeFs(), '/x');
  expect((await s.add('   ')).ok).toBe(false);  // err, não um throw
});

Uma pergunta fecha o desenho do store: quais métodos precisam de Result + tryCatchAsync e quais não? A regra é uma só pergunta — "este método cruza a porta (toca o fs)?". Se cruza, ele pode lançar e precisa da assinatura async-Result; se só lê estado em memória, retorna direto. É a justificativa da resposta "sua vez" sobre o count():

08 · NoteStore vs MemoryStore: o que é igual, o que reduzimos

O NoteStore não é um brinquedo paralelo — é o MemoryStore entregue, podado ao mínimo. Veja lado a lado o que foi preservado (o esqueleto que define um subsistema) e o que foi reduzido (recursos que o lab não precisa para ensinar o padrão):

O gráfico abaixo torna a poda visível: a área verde é o esqueleto compartilhado (idêntico nos dois); a área clara são os recursos que o store entregue tem a mais — e que viram seus exercícios:

A fórmula do subsistema — calcule a superfície

Toda classe-store custa um piso fixo de linhas (o esqueleto: construtor + load + list + os imports) mais um custo por método de domínio que cruza a porta. Mexa os sliders e veja a superfície (e a barra de "quanto é esqueleto vs domínio") mudar — é uma estimativa de guardanapo para dimensionar um subsistema novo:

09 · Sua vez — estenda o store

10 · Como isso se encaixa

Este lab não constrói uma peça avulsa: ele aplica o padrão de ports-e-injeção das lições de deep-dive para erguer um subsistema novo que pluga no mesmo motor que o MemoryStore e o SkillStore já plugam. O NoteStore que você escreveu tem a mesma forma — IO injetado, validado na fronteira, nunca-lança, limitado — então o que vale para ele vale para qualquer store que o motor execute. Veja onde a peça entra: o que alimenta a construção (a montante) e o que ela passa a alimentar (a jusante) depois de pronta.

As peças com que este lab se conecta — cada uma é uma lição que abre uma face deste mesmo padrão:

Onde você está na metodologia. O motor do Alembic é um loop — aprender → analisar → executar uma unidade → verificar na fronteira real → decidir — e cada subsistema é uma peça que esse loop executa e verifica. Este lab é a oficina: você fabrica uma peça nova com a forma exata que o motor exige, para que ela atravesse os gates (Lição 17) e plugue no loop do agente (Lição 19) sem nenhum caso especial. Aprender o esqueleto aqui é o que torna a Lição 29 ("a receita") aplicável a qualquer subsistema futuro. Para ver a esteira inteira em movimento, abra o mapa interativo da metodologia.

11 · Na prática

Este é um lab de construção: a prova não é um comando de runtime, é o subsistema compilando e o teste passando. O ciclo de verdade tem três comandos — andaime o pacote, rode só o teste dele enquanto itera, e feche com a baseline completa do repositório. São os mesmos comandos que o CLAUDE.md manda manter verdes a cada mudança de código.

1) Rode só o teste do pacote em que o store vive enquanto você itera no add() — o ciclo de feedback curto:

# roda apenas o pacote do store (substitua <pkg> pelo seu, ex.: hermes)
pnpm --filter @alembic/<pkg> test

# saída esperada (forma — Vitest):
#  ✓ src/notes/note-store.test.ts (3)
#    ✓ rejects an empty note and never throws
#    ✓ adds a valid note and bumps the count
#    ✓ refuses past the cap with an err
#  Test Files  1 passed (1)
#       Tests  3 passed (3)

2) Antes de dar a unidade por pronta, feche com a baseline do repositório inteiro — tipos, build e todos os testes. É o portão do CLAUDE.md ("Every code change must keep these green"):

# a baseline canônica — precisa terminar com exit 0
pnpm -r typecheck && pnpm -r build && pnpm -w test

# o que observar:
#  - typecheck: 0 erros (se quebrar após mexer num pacote, rode `pnpm -r build`
#    para os dependentes verem o novo .d.ts)
#  - build: todos os pacotes compilam
#  - test: a contagem total sobe ou fica igual — nunca cai

Vale ver o ciclo como três passos numa esteira — itera no curto, fecha no completo, e só então a peça é uma unidade pronta:

Fixe os conceitos (flashcards)

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