Fundação: Contratos e ETL

Em biblioteca do Alembic, erro não é exceção voando pela pilha — é um valor. O Result<T, E> de packages/contracts/src/result.ts é uma união discriminada em ok: ou Ok<T> com value, ou Err<E> com error (result.ts:10–20). Quem chama é OBRIGADO pelo compilador a olhar o ramo de falha antes de tocar no valor. É isso que "fail-closed" significa na prática: o caminho de erro não é opcional, esquecível ou silencioso.

Pense como… um disjuntor: quando algo dá errado, o circuito abre e NADA passa — em vez de deixar a corrente (dado inválido) seguir e queimar a casa. Onde a analogia quebra: um disjuntor você rearma no escuro; um err carrega a causa dentro dele.

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 });

Os utilitários tryCatch e tryCatchAsync (result.ts:46–69) embrulham código que lança e devolvem Result — tryCatchAsync nunca rejeita. Para chamadas de modelo existe o irmão mais rico, ModelRunResult (lição 02); os dois leem igual no call site porque ambos discriminam em ok (result.ts:5–8).

packages/contracts/src/tier.ts:15–22 define a escada T0…T4: T0 silencioso/autônomo, T1–T3 autônomos com escrutínio crescente (isAutonomous, tier.ts:59–60), e T4 = PARK — retido até council + humano. O detalhe de projeto que revela a filosofia: DEFAULT_TIER = Tier.T4 (tier.ts:51). Trabalho não classificado nasce estacionado, não executado. O default é a trava, não a permissão.

Ortogonal à escada existe o marcador LOCAL (tier.ts:36–37): trabalho pregado em modelo local/$0 independente do tier — o caminho de privacidade e de custo zero.

O catálogo de modelos vive em packages/contracts/src/registry.ts:57–230. Cada entrada declara modelId, adapterId (em geral cliproxyapi, ou local para a pista $0), tier e preço por 1k tokens — tudo validado por modelRegistryEntrySchema (Zod, registry.ts:8–30). Quando ninguém pina um modelId, pickCheapestForTier(tier) (registry.ts:244–257) faz um leilão: filtra o tier e reduz pelo custo combinado input+output.

@alembic/etl é a camada L0: quem caminha o corpus, deduplica, valida e roteia — a $0, sem modelo nenhum. Toda a E/S passa por uma porta injetável, o FsPort (packages/etl/src/fs-port.ts:61–83), com dois invariantes gravados no doc do arquivo (fs-port.ts:19–24): leituras do corpus são READ-ONLY; saídas são APPEND-ONLY (só appendLine escreve, mais ensureDir uma vez). Um writeFileAtomic (tmp + rename, fs-port.ts:172–176) cobre os stores que precisam de troca atômica — um leitor concorrente nunca vê arquivo pela metade.

Peças, uma a uma: walkCorpus (pipeline.ts:114–120) percorre em profundidade sem bufferizar e não desce em Repos/Models/Repos/Prompts (priors.ts:34–37); sha256Hex (dedupe.ts:38–39) é a chave de conteúdo — conteúdo idêntico em qualquer lugar colapsa em um; o ledger _alembic-processed.jsonl é só-append (dedupe.ts:14–17), então re-rodar um corpus inalterado é no-op; e cada linha termina num de cinco desfechos tipados (pipeline.ts:44–49).

Priors por família: roteamento antes de qualquer modelo

Cada família de fonte carrega um prior barato e determinístico (priors.ts:54–64): Transcripts→T2 (0.9), Discord/Circle→T2, Skool→T2, Whatsapp/Bookmarks/Skills→T1, Repos→T1 — e Unknown→T0 (0.1). Item cuja família mira acima do piso T0 vira residue para os tiers pagos; o resto o T0 resolve sozinho, de graça.

export const classifyFamily = (relativePath: string): SourceFamily => {
  const head = relativePath.split(/[\\/]/).find((seg) => seg.length > 0) ?? '';
  const match = SOURCE_FAMILIES.find(
    (family) => family !== 'Unknown' && family === head,
  );
  return match ?? 'Unknown';
};

Regra prática: distill sempre no pai das famílias. Para escopar UMA família só, a técnica provada é materializar apenas os package.jsonl daquela família numa árvore-espelho (o truque do cpio) — o path relativo continua começando com o nome da família.