A disciplina de ports-and-injection

Por que todos os sete subsistemas da fusão se parecem? Porque cada um obedece a uma única disciplina: depender de portas injetadas (FsPort, Clock, adapter, idFactory), retornar Result em toda fronteira, validar entrada não confiável com Zod e nunca lançar exceção. A disciplina não é decoração — é o que torna o motor testável, determinístico e agnóstico de store (ADR-0009).

01 · O contrato: um Result que nunca lança

Antes das portas, antes da injeção, existe uma peça da qual tudo depende. Um Result é um valor que é ou sucesso ou falha — nunca uma exceção. Pense numa encomenda dos correios: ou ela chega com o pacote, ou chega com um aviso explicando por que não veio. Em nenhum caso o carteiro some no meio do caminho. É de @alembic/contracts:

// packages/contracts/src/result.ts:10-26
export interface Ok<T> { readonly ok: true;  readonly value: T; }
export interface Err<E> { readonly ok: false; readonly error: E; }
export type Result<T, E = Error> = Ok<T> | Err<E>;

export const ok  = <T>(value: T): Ok<T>  => ({ ok: true,  value });
export const err = <E>(error: E): Err<E> => ({ ok: false, error });

O booleano ok é uma tag de união discriminada: depois de if (!r.ok) return r; o compilador sabe que o resto é r.value. Não há terceiro estado nem fluxo de controle oculto — uma falha é um valor que você tem de tratar, não uma exceção que desenrola a pilha.

O único lugar onde um try/catch cabe é bem na borda, encapsulando uma chamada que lança de volta no contrato:

// packages/contracts/src/result.ts:57-69 — "Never rejects."
/** Wrap an async throwing function as a Result. Never rejects. */
export const tryCatchAsync = async <T>(
  fn: () => Promise<T>,
  onError: (cause: unknown) => Error = toError,
): Promise<Result<T, Error>> => {
  try { return ok(await fn()); }
  catch (cause) { return err(onError(cause)); }
};

02 · O padrão: dependa de uma porta, não de uma concretização

Com o contrato firme, vem a segunda metade da disciplina. Uma porta é uma interface injetada — o subsistema declara do que precisa e o chamador fornece. Nenhum subsistema constrói seu próprio filesystem, relógio, modelo ou cliente de rede. É como uma tomada na parede: o aparelho não tem um gerador embutido; ele declara um plugue e você liga onde quiser — na rede elétrica de verdade, ou numa bateria de teste. Quatro costuras recorrem na fusão:

03 · A mesma forma, quatro vezes

A prova de que isto é disciplina, e não acaso, é repetição. O mesmo formato aparece em quatro kernels diferentes do Hermes — cada um injeta o que precisa e devolve Result.

FsPort + Clock — o usage store do curador

O construtor recebe seu filesystem, o caminho do arquivo e seu relógio. Não constrói nenhum deles:

// packages/hermes/src/curator/usage-store.ts:58-63
export class UsageStore {
  constructor(
    private readonly fs: FsPort,          // IO injetado — sem node:fs
    private readonly sidecarPath: string,  // o caminho é argumento, sem home global
    private readonly clock: Clock,        // tempo injetado — sem Date.now()
  ) {}

Escritas atômicas passam por FsPort.writeFileAtomic para que um crash nunca deixe um sidecar meio-escrito; leituras são best-effort (um arquivo corrompido é tratado como vazio, retornando ok, então uma chamada de telemetria de hot-path não pode quebrar o host). A assimetria é deliberada: leitura corrompida → ok(vazio), escrita falha → err.

Uma porta de backend — busca/extração web

O kernel web não importa nenhum SDK e nenhum backend concreto. Ele declara duas costuras injetadas — o provedor e um compressor opcional — ambas retornando Result:

// packages/hermes/src/web/types.ts:120-140
export interface WebBackend {
  search(query: WebSearchQuery): Promise<Result<readonly WebSearchResult[], Error>>;
  extract(url: string): Promise<Result<WebExtractResult, Error>>;
}
// Costura opcional de compressão LLM — encapsula UMA chamada de ModelAdapter
// em prod; ausente ⇒ conteúdo bruto é retornado sem alteração.
export type Compressor = (
  text: string, instruction: string,
) => Promise<Result<string, Error>>;

Uma falha de rede é err; uma busca vazia é ok([]) — a diferença é preservada no tipo. Esta é exatamente a costura que o ciclo de aprendizado usa no seu ReviewProposer: "uma chamada de modelo em prod, um fake em testes".

Um idFactory — o gateway de clarify

A primitiva bloqueante de humano-no-loop precisa de ids. Ela recebe um id factory injetado, com padrão de contador monotônico — nunca Math.random() ou Date.now(), que a VM de plano do motor rejeita e que quebraria o replay:

// packages/hermes/src/clarify/gateway.ts:72-74 + 176-182
constructor(options: ClarifyGatewayOptions = {}) {
  this.mintId = options.idFactory ?? monotonicIdFactory();  // injetado, padrão determinístico
}
export const monotonicIdFactory = (prefix = 'clarify'): (() => ClarifyId) => {
  let n = 0;
  return () => { n += 1; return `${prefix}-${n}`; };
};

Node não tem thread bloqueante, então o gateway é uma promise + registro de resolvers + timeout: ask() registra uma entrada pendente sob um id cunhado, arma um setTimeout, e retorna a promise aguardada. No timeout a entrada é descartada e a promise resolve para err — nunca trava e nunca lança.

04 · A fronteira: Zod entra → Result sai

Há um terceiro fio na disciplina, e é onde as duas metades se encontram. Qualquer coisa de fora do programa — a proposta de um modelo, a resposta de clarify de uma plataforma, o JSON de um backend — é não confiável. Trate-a como a fila da imigração: ninguém entra sem ter o documento conferido. Então ela é validada com Zod na fronteira, e uma falha vira err, não uma exceção lançada:

// packages/hermes/src/clarify/gateway.ts:86-89
const parsed = clarifyQuestionSchema.safeParse(question);
if (!parsed.success) {
  return err(new Error(`Invalid clarify question: ${parsed.error.message}`));
}
// …e em learning/review.ts:83-85, a saída do proposer (modelo não confiável) é
// reviewProposalSchema.safeParse'd antes de qualquer escrita. Mesma forma, toda fronteira.

05 · Refatore na mão (passo a passo → agora você)

Você viu a disciplina em quatro kernels prontos. Agora aplique-a você: pegue uma função "ingênua" (que constrói o mundo e lança) e leve-a até a forma da fusão. Recuperar o procedimento fixa mais que reler o resultado.

06 · Injetado vs hardcoded — o trade-off lado a lado

Toda a disciplina gira em torno de uma escolha: o kernel recebe o mundo (injetado) ou o constrói (hardcoded)? Veja o mesmo kernel nas duas formas — a tabela diz os números, o diagrama torna a diferença visível.

07 · O raio de explosão de uma troca de backend

Aqui a disciplina vira número. Quando você troca o provedor (frontier → local → fake offline), quantos arquivos mudam? Com portas, só o ponto de composição (quem injeta) muda; o kernel fica intacto. Sem portas, cada arquivo que importou o SDK direto precisa ser reescrito. Arraste para sentir o trade-off:

08 · O retorno — por que dar todo esse trabalho (ADR-0009)

As três disciplinas — Result, portas, Zod-na-fronteira — não são três regras soltas. São uma só ideia vista de três ângulos, e juntas pagam três dividendos:

Confusões comuns

09 · Como isso se encaixa

Esta lição não descreve um subsistema — descreve o padrão que está debaixo de todos eles. Ports-and-injection não é uma peça da pipeline; é a regra que cada peça da pipeline obedece. Por isso ela não aparece como uma caixa no fluxo: ela é o chão sobre o qual o fluxo inteiro anda. Veja onde a disciplina toca a máquina:

10 · Na prática

A disciplina não é teoria: é exatamente o que deixa você provar um subsistema sem rede, sem disco e sem relógio real. O teste injeta um FsPort fake, um Clock fixo e um backend enlatado — e o kernel roda determinístico. Rode você mesmo o pacote onde os quatro kernels desta lição vivem:

# roda só o pacote @alembic/hermes — onde vivem usage-store, web, clarify, learning
pnpm --filter @alembic/hermes test
# …
# ✓ src/curator/curator.test.ts   (FsPort fake + Clock fixo → zero IO)
# ✓ src/web/web.test.ts           (WebBackend fake → err ≠ ok([]))
# ✓ src/clarify/clarify.test.ts   (idFactory monotônico → ids determinísticos)
# ✓ src/learning/review.test.ts   (proposta safeParse'd na fronteira)
# Test Files  N passed
# Tests       N passed   ← todos com portas FALSAS, nada toca o mundo

A contagem exata de casos varia conforme o pacote evolui — o que importa é que passa sem tocar disco, rede ou relógio. É a disciplina virando prova. [uncertain] o número (N) de casos depende da versão do repo; o conjunto real aparece quando você roda o comando acima.

E a mesma disciplina é o que mantém o monorepo inteiro verde — a baseline que todo change precisa passar (CLAUDE.md):

# a baseline de build/test do projeto inteiro (CLAUDE.md)
pnpm -r typecheck && pnpm -r build && pnpm -w test
# typecheck: o compilador exige que você trate !r.ok antes de ler r.value
# test:      kernels rodam contra portas fake — determinístico, sem rede

Fixe os conceitos (flashcards)

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