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.

A receita num relance

Passo 1–2 — portas e schemas primeiro

Comece com types.ts. Defina o que uma entrada válida é (Zod) e do que o subsistema depende (interfaces de porta). Os subsistemas entregues fazem exatamente isso — ex.: as portas WebBackend + Compressor do subsistema web, as portas ReviewProposer + ReviewGate do loop de aprendizado. Portas são tipos, nunca classes concretas:

// 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

Passo 3–4 — Result em tudo, sem globais

O arquivo de implementação é funções ou uma classe sobre essas portas. Todo caminho falível retorna Result; IO é envolvido em tryCatchAsync; tempo/aleatoriedade vêm de um Clock/fábrica de ids injetados, nunca um global (Lição 28). É 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
};

Passo 5 — a pergunta da dependência

Antes de adicionar um pacote, pergunte: um global já no runtime consegue fazer isso? Os subsistemas web e media responderam que sim — usam o fetch global via 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 YAML (Lição 12). A regra: "Não adicione novas dependências sem justificativa." Uma nova dep é uma superfície de supply-chain e um risco de clean-room — mereça-a ou evite-a.

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:

# 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

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). Depois rode a baseline e confirme que a contagem 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.

Confusões comuns