@alembic/harness — o funil T0→T3 e as duas cadeias

O harness é onde as três lições anteriores viram UMA máquina. runFunnel pega um corpus e o conduz por quatro tiers: T0 — o substrato determinístico da lição 03 (100% do corpus, $0); T1 — um modelo LOCAL extrai um BusinessSignal de cada item do residue; T2 — uma shortlist FRONTIER refina os sinais fortes, em lotes, cada chamada paga pré-aprovada pelo BudgetGuard; T3 — um council de três membros debate e um verifier maker-checker decide: só um GO verificado emite edges + learnings.

E há três invariantes que o arquivo declara “load-bearing, do not regress” (funnel.ts:72-84): PII — sinal de canal privado é redigido e passa por assertRedactedForEmit ANTES de qualquer escrita (não passou ⇒ descartado, nunca emitido); BUDGET — toda chamada paga é embrulhada num check fail-closed (projeção estoura o cap ⇒ a chamada NÃO acontece e o tier degrada); APPEND-ONLY — resultados fluem para os stores por escrita validada e content-addressed; a fonte permanece read-only.

Pense como… uma refinaria com dois dutos de saída: o mesmo petróleo bruto (residue) alimenta o duto de combustível (signals → oportunidades de negócio) e o duto de lubrificante (learnings → melhoria do próprio motor). Cada duto tem seu PRÓPRIO medidor de vazão e sua PRÓPRIA válvula de corte — entupir um jamais fecha o outro. Onde quebra: numa refinaria os dutos competem pelo mesmo cru; aqui um item pode ser processado PELAS DUAS rotas (funnel.ts:807-809).

A ADR-0002 diz: “o budget vira dois knobs, um por cadeia de valor”. Em código, o campo budget de FunnelOptions aceita TRÊS formas (funnel.ts:167-174): um número ou um BudgetGuard (a forma LEGADA — funda só a cadeia de sinais, run byte-idêntico ao de sempre) ou um mapa RouteBudgets {signals, learnings} — a forma de dois knobs que ATIVA a cadeia de learnings com cap independente (resolveRouteBudgets, budget.ts:216-221).

O contrato de honestidade do relatório: report.routes só EXISTE numa run de dois knobs (funnel.ts:150-160 + 919-922) — o JSON de uma run legada permanece byte-idêntico para consumidores. E routes.signals.budgetBlocked soma TODOS os bloqueios fail-closed da cadeia: T1 + T2 + membros do council T3 (funnel.ts:930-931).

Depois do T0, o funil percorre o corpus de novo e monta a fila dos tiers pagos: collectResidue (funnel.ts:316-341) pega cada arquivo cuja família mira tier > T0, valida cada linha contra o contrato wiki (só valid passa) e empacota um ResidueItem: hash, caminho, família, canal (para o gate de PII) e — o campo que alimenta o modelo — a evidência.

É aqui que entra a função pequena e importante: bridgeEvidenceOf (funnel.ts:308-314). Uma linha de bridge (o wiki-bridge da lição 03) carrega um campo evidence com o texto destilado REAL que o adapter de família escreveu. A função prefere esse campo ao registro serializado inteiro — para o sinal do T1 citar conteúdo, e não um bundle de paths. Linha legada sem evidence? Cai no raw, sem quebrar.

O guarda é um medidor por run, sem IO: capUsd fixo, spentUsd() acumulado, e o protocolo em dois tempos — check(estimativa) ANTES de cada chamada paga, record(custo real) DEPOIS. Se gasto + projeção ultrapassa o cap, volta um BudgetExceeded tipado ({reason, spentUsd, projectedUsd, capUsd, message}) e a chamada não acontece. Ele “never silently proceeds and never throws” (budget.ts:29-40).

A projeção usa uma estimativa grosseira e barata: ~4 caracteres por token de entrada + 256 de saída (estimateUsage, funnel.ts:467-470), precificada pela tarifa do TIER no registry — mesmo quando o modelo de fio foi sobrescrito pelo catálogo, a cobrança usa o pricingModelId do tier, nunca fica sem medição (funnel.ts:343-348 + 409-426).

Em 2026-07-06 a cadeia de learnings produziu pela primeira vez na história do motor. Não por um recurso novo — o código já estava pronto — mas porque três pedras saíram do caminho, todas ensinadas neste módulo:

A função que faz o T1 citar conteúdo real (e não paths) — pequena o bastante para caber inteira:

Feche o módulo 1 com as quatro cartas do operador de funil.