Ports e injeção

Quando cinco subsistemas diferentes têm o mesmo formato, não é coincidência — é uma disciplina imposta de propósito. Aprenda a disciplina uma vez e você lê qualquer pedaço da fusão sem reaprender nada.

Tudo se apoia num tipo minúsculo de @alembic/contracts. Um Result é um valor que é ou sucesso ou falha — nunca uma exceção.

Aqui está o tipo inteiro — minúsculo de propósito:

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: após 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ê deve 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:

/** Encapsula uma função async que lança como Result. Nunca rejeita. */
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)); }
};

À esquerda, a exceção escapa da pilha — fácil de esquecer. À direita, a falha está no tipo: o compilador não te deixa ler .value antes de tratar !r.ok.

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.

Quatro costuras recorrem por toda a fusão:

O kernel no centro não importa fs, nem clock, nem nenhum SDK — só as portas. Em oliva, as costuras de determinismo; em slate, as de rede/modelo.

A teoria fica concreta quando você vê o mesmo formato repetido em cinco arquivos reais. Use as abas do explorador para acender cada porta no diagrama, depois leia o trecho de código que a prova.

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:

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. Decidir qual falha é fatal e qual é tolerável é metade da arte de uma porta bem desenhada.

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:

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:

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.

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. Então é validada com Zod na fronteira, e uma falha vira err, não uma exceção lançada.

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.

Toda essa disciplina compra três coisas concretas. Não são abstrações de arquiteto — cada uma resolve um problema real de quem mantém o sistema.

Duas objeções aparecem sempre que alguém vê esse padrão pela primeira vez. Ambas têm uma resposta curta e firme.

Passe pelo deck para fixar a sequência, vire os cartões para praticar recuperação, e leve as dez ideias.

Cartões de memória