Estendendo a fusão: a receita para um novo subsistema

Você leu sete subsistemas entregues e construiu dois próprios nos labs. Agora destile isso num checklist que um agente futuro pode seguir para adicionar um oitavo subsistema @alembic/hermes sem redescobrir as convenções. A receita não é gosto arbitrário — cada passo remete a um invariante ou ADR que você já conheceu. Siga-a e seu subsistema vai parecer que sempre esteve lá; pule um passo e o CI ou um revisor te pega, porque as regras são impostas, não sugeridas.

01 · A forma que todo subsistema compartilha

Antes da receita de passos, veja o formato físico: o que é uma pasta de subsistema no disco e como ela se conecta ao resto do pacote. Os sete subsistemas entregues não são sete designs diferentes — são sete cópias do mesmo molde. Reconhecer o molde é o que te deixa adicionar o oitavo sem hesitar.

A receita inteira cabe num quadro. Cada passo é uma caixa; cada caixa traz por que ela existe — o invariante ou ADR que a impõe. Leia o pipeline da esquerda (portas) até a direita (suíte verde):

A tabela abaixo é a mesma receita em texto — cada passo ao lado da regra que o obriga. Guarde esta correspondência: ela é o que transforma "convenção" em "contrato".

02 · Passo 1–2 — portas e schemas primeiro

Comece com types.ts. Antes de qualquer lógica, declare duas coisas: o que uma entrada válida é (Zod) e do que o subsistema depende (interfaces de porta). Pense numa porta como a tomada na parede: a implementação não sabe (nem quer saber) o que está plugado do outro lado — pode ser o backend real em produção ou um fake no teste. A tomada é um tipo, nunca uma classe concreta.

// packages/hermes/src/<name>/types.ts
import { z } from 'zod';

export const requestSchema = z.object({ /* … campos limitados … */ });
export type Request = z.infer<typeof requestSchema>;

// Uma porta = uma capacidade injetada, nunca um import concreto:
export type Backend = (req: Request) =>
  Promise<import('@alembic/contracts').Result<Response, Error>>;   // nunca lança

Porta injetada vs. import concreto — o contraste

Por que insistir em "porta" em vez de simplesmente import { fetch } e pronto? Porque a tomada é o que separa o que o subsistema faz de como o efeito colateral acontece. Veja os dois desenhos lado a lado:

O passo 2 é o portão de entrada: toda entrada passa por safeParse antes de tocar a lógica. A razão é dura — no Alembic, as entradas frequentemente são saída de um modelo ou da rede, isto é, não confiáveis por padrão. O schema é a fronteira onde dado bruto vira dado tipado, ou é rejeitado como erro:

03 · Passo 3–4 — Result em tudo, sem globais

O arquivo de implementação é funções (ou uma classe) sobre aquelas portas. Duas regras o governam, e ambas você já conheceu: todo caminho falível retorna Result (nunca um throw que vaza para fora), e tempo/aleatoriedade vêm de uma porta injetada — nunca de um global. É o esqueleto exato do Lab 1; não é um brinquedo, é o padrão de produção no tamanho mínimo.

// packages/hermes/src/<name>/<name>.ts
import { ok, err, tryCatchAsync, type Result } from '@alembic/contracts';
import { requestSchema, type Backend } from './types.js';

export const doThing = async (
  input: unknown, deps: { backend: Backend; now: () => number },
): Promise<Result<Response, Error>> => {
  const parsed = requestSchema.safeParse(input);          // ② Zod na fronteira
  if (!parsed.success) return err(new Error(parsed.error.message));
  return deps.backend(parsed.data);                        // ③ Result passa, ④ sem globais
};

Por que Result em vez de throw

Um throw some do tipo: quem chama não vê, pelo tipo, que aquela função pode explodir — descobre em runtime, talvez em produção. O Result<T, Error> torna o erro parte do contrato: o tipo de retorno diz que pode falhar, e o compilador obriga o chamador a tratar os dois ramos. É a "cintura estreita" do pacote — o erro flui como dado, não como exceção que pula a pilha.

04 · Passo 5 — a pergunta da dependência

Antes de adicionar um pacote ao package.json, faça uma pergunta: um global que já está no runtime consegue fazer isso? Os subsistemas web e media responderam que sim — usam o fetch global por trás de um fino createFetchBackend em vez de adicionar um cliente HTTP (Lição 11). O subsistema skills escreveu seu próprio parser de frontmatter escalar, sem dependências, em vez de puxar uma lib de YAML (Lição 12). A regra do CLAUDE.md é direta: "não adicione novas dependências sem justificativa."

05 · Quanto custa, de fato, uma dependência? (calculadora)

"Uma dependência a mais" soa barato. Mas cada pacote chega com seus próprios sub-dependentes (a árvore transitiva). Arraste o slider: veja a árvore total que entra no projeto — e por que o degrau de 0 → 1 é o que mais pesa, não o de 9 → 10.

06 · Passo 6 — ligue a segurança de testes

Cada pacote carrega seu próprio vitest.config.ts (o pacote hermes tem um). Combine a config root endurecida — timeouts limitados e pool:'forks' — e sempre rode a suíte pelo wrapper de grupo de processo, nunca vitest puro. Por quê? Um teste que abre um socket ou inicia um timer e nunca o fecha pode órfãozar um worker — um processo que continua queimando CPU por horas depois que a suíte "terminou" (Lição 25). A config é a primeira linha de defesa; o test:safe é o piso.

# rode a suíte inteira com segurança (Lição 25):
pnpm test:safe            # run limitado no próprio grupo → mata o grupo + varredura
# ou um pacote:
pnpm --filter @alembic/hermes test

07 · Passo 7–8 — exporte, documente, verifique

Re-exporte todo símbolo público de src/index.ts com um comentário de cabeçalho nomeando a proveniência CLONE/ADAPT/IGNORE e as seções do mapa-fonte (leia o bloco de qualquer subsistema em index.ts — todos fazem isso). É o que torna o subsistema descobrível e mantém o rastro de clean-room. Depois rode a baseline e confirme que a contagem de testes moveu na direção certa:

# a baseline de build/test que toda mudança deve manter verde (CLAUDE.md):
pnpm -r typecheck && pnpm -r build && pnpm -w test

A disciplina fecha aqui: "Toda feature nova precisa de testes; a contagem total de testes deve aumentar ou ficar estável." Um subsistema sem testes — ou um que derruba a contagem — não está pronto. Veja as duas trajetórias:

08 · O fluxograma da receita inteira (decisão)

Junte os oito passos numa única decisão que um agente futuro segue de cima a baixo. Cada losango é um portão imposto pelo CI, pela VM de plano ou por um revisor — não passa enquanto não estiver verde. Siga as setas: do "novo subsistema" até "merge", todo ramo de falha aponta para o que corrigir.

Confusões comuns

09 · O checklist copia-e-cola

Tudo destilado numa lista que um agente marca item a item. O diagrama mostra o estado de cada caixa; a lista abaixo é o texto literal para colar num PR ou numa issue.

10 · Exemplo resolvido — um subsistema do zero, passo a passo

A receita abstrata vira concreta quando você a aplica a um caso. Vamos seguir os oito passos para um subsistema hipotético digest/ (resumir o conteúdo de um pacote do wiki) — exatamente o que um agente futuro faria. Em cada passo, a coluna da direita mostra o portão que verificaria aquele passo. Nota: digest é o <name> de exemplo da receita, não um subsistema já entregue — os sete entregues são memory · learning · clarify · web · skills · curator · media.

O mesmo caso, visto como um traço: o subsistema digest entrando por cada um dos oito portões, com o veredito de cada um. É a receita "rodando" sobre um exemplo — repare que todo portão fica verde porque cada passo foi feito na ordem.

11 · Como isso se encaixa

Esta receita não é uma lição avulsa: é o nó que amarra quatro peças do curso num único caminho repetível — "adicionar um subsistema". Ela toma o framework de fusão (Lição 21) como a decisão de o quê portar, o padrão de ports & injeção (Lição 05) como a forma de cada arquivo, os labs (Lições 22–23) como o treino de construir a peça à mão, e a segurança de testes (Lição 25) como o piso de como rodá-la — e os funde nos 8 passos. Veja o que alimenta a receita (a montante) e o que ela passa a produzir (a jusante): um subsistema que atravessa os gates e pluga no motor.

As peças que esta receita amarra — cada uma é uma lição que abre uma face do mesmo caminho:

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. Esta lição é a planta da fábrica: o procedimento que pega uma peça nova e a faz nascer com a forma exata que o motor exige, atravessar os gates (Lição 17) e plugar no loop do agente (Lição 19) sem nenhum caso especial. As Lições 22–23 são a oficina (você fabrica uma peça à mão); esta receita é o manual que torna esse trabalho repetível para qualquer subsistema futuro. Para ver a esteira inteira em movimento, abra o mapa interativo da metodologia.

12 · Na prática

A receita vira comandos concretos. Como um subsistema é uma peça do motor (não um run montado), a prova certa não é um alembic run — é o pacote compilando e os testes passando. O ciclo de verdade tem três comandos, na ordem da receita: rode só o teste do pacote enquanto itera, rode a suíte inteira com a segurança de testes da Lição 25, e feche com a baseline completa do CLAUDE.md. São exatamente os comandos que o projeto manda manter verdes a cada mudança de código.

1) Com a pasta <new>/ e seu vitest.config.ts por pacote no lugar (passo 6), rode só o teste do pacote enquanto itera — o ciclo de feedback curto:

# roda apenas o pacote do novo subsistema (substitua <new> pelo nome do pacote)
pnpm --filter @alembic/<new> test

# saída esperada (forma — Vitest):
#  ✓ src/<name>/<name>.test.ts (3)
#    ✓ rejeita entrada inválida e nunca lança
#    ✓ valida e retorna ok no caminho feliz
#    ✓ usa now() injetado — determinístico
#  Test Files  1 passed (1)
#       Tests  3 passed (3)

2) Rode a suíte inteira pela segurança de testes — nunca vitest puro. O wrapper roda no próprio grupo de processo e o mata ao final, então um teste que abre um socket ou timer não orfaniza um worker queimando CPU por horas (Lição 25):

# roda a suíte inteira com segurança de grupo de processo (Lição 25):
pnpm test:safe

# o que observar:
#  - a suíte termina e o processo volta ao prompt (nada fica em segundo plano)
#  - nenhum worker órfão (PPID=1) consumindo CPU depois do fim

3) 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"), o passo 8 da receita:

# 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 uma esteira de quatro passos — scaffold, itera no curto, roda seguro, fecha no completo — e só então a peça é uma unidade pronta que pluga no motor:

Fixe a receita (flashcards)

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