Layer L0: Contracts + ETL — O Substrate

@alembic/contracts — O Spine (6 arquivos)

Tudo no projeto é construído sobre esses tipos. Qualquer mudança aqui tem impacto sistêmico.

ETL T0 Pipeline (o único tier que sempre roda)

// packages/etl/src/pipeline.ts:27
export const runT0Pipeline = async (...) => {
  // walkCorpus (stream, nunca bufferiza)
  // para cada .jsonl:
  //   - sha256Hex
  //   - loadDedupeIndex + recordProcessed (append-only ledger)
  //   - validateLlmWikiContract
  //   - scorePackage (6 eixos determinísticos)
  //   - priorFor + routesToResidue
  //   - emite para _alembic-residue.jsonl ou scored
}

PII Redaction + Emit Gate (a barreira de privacidade)

// packages/etl/src/pii.ts (principal)
export const assertRedactedForEmit = (signal, channel) => {
  if (isPrivateChannel(channel)) {
    // deve estar redigido
    if (!isRedacted(signal)) return err(...)
  }
  return ok(signal)
}

// Chamado em emitSafeSignal (harness/funnel.ts:243) ANTES de qualquer write no store

Deep line-by-line adicional: Em pii.ts há PRIVATE_CHANNELS (whatsapp, discord, skool, circle). Qualquer sinal dessas famílias passa por redactSignal antes do assert. O gate é fail-closed: se falhar, o sinal nunca chega ao store de oportunidade. Isso é chamado em dois lugares críticos: emitSafeSignal no funnel e antes de qualquer append no stores.

Stores (append-only, content-addressed)

packages/etl/src/stores.ts: — appendOpportunityRecord, appendLearning, usando FsPort injetável + atomic writes + SHA content addressing (linhas principais em appendStoreRecord).

Deep line-by-line: Todo write em stores é content-addressed (hash do conteúdo + timestamp). Isso permite replay exato e dedupe global. O FsPort é injetável, permitindo testes com memória (ver fs-port.ts).

Como Verificar Esta Camada (verify)

pnpm test packages/etl
# Foco:
# - pipeline.test.ts
# - pii.test.ts (redaction + assert gate)
# - stores.test.ts (atomic + dedupe)

# Teste manual forte:
alembic distill ./corpus --offline --dataDir /tmp/test0
cat /tmp/test0/_alembic-residue.jsonl | head -5
cat /tmp/test0/_alembic-processed.jsonl | wc -l

Common confusions: Achar que T0 "só filtra". Não — ele faz dedupe incremental por SHA, valida contrato, score determinístico de 6 eixos e roteamento por prior antes de qualquer LLM.

Practice task: 1. Leia contracts/result.ts:46-69 (tryCatchAsync). 2. Leia etl/pipeline.ts:40-59. 3. Rode T0 pequeno e inspecione residue + ledger. 4. Injete sinal privado sem redação e observe o gate no próximo tier. 5. Compare o comportamento com e sem --offline.

Common Confusions + Practice

Confusão: "T0 é só um filtro simples". Não. É um pipeline completo com dedupe incremental por SHA, validação de contrato, scoring determinístico de 6 eixos e roteamento por família/prior.

Prática: 1. Leia contracts/result.ts:46-69 (tryCatchAsync). 2. Leia etl/pipeline.ts:40-59 (RESIDUE_NAME e ResidueRecord). 3. Rode um T0 com corpus pequeno e inspecione o residue + processed ledger. 4. Tente injetar um item de canal privado sem redação no residue e veja o gate em ação no próximo tier.

Resumo da Camada L0

Source Anchors (Evidência Direta)

Por que L0 é o Foundation

Todo sinal de negócio ou learning que chega em T1, T2 ou T3 já passou pelo T0. O T0 é o grande equalizador de custo e o primeiro filtro de qualidade. Os contratos em packages/contracts/src/ são o que permite que o resto do sistema (adapters, council, harness, factory) seja agnóstico de provider e extremamente testável.

Entender linha a linha o Result, o tryCatchAsync, o runT0Pipeline, o pii gate e os stores content-addressed é entender a fundação sobre a qual todo o resto do Alembic foi construído.

Esta camada é onde o "barato" e o "seguro" são realmente implementados. Sem um T0 forte, todo o resto do funnel fica caro ou arriscado. Sem contratos claros, o sistema inteiro perde coesão.

Qualquer pessoa que queira contribuir com o projeto ou auditar sua segurança deve começar por aqui. É o alicerce.

Em resumo: L0 é onde o dinheiro é economizado e a privacidade é protegida antes de qualquer chamada cara a frontier models ou council.

Por isso esta deep dive é tão importante: sem dominar L0, é impossível entender por que o sistema consegue ser tão barato e seguro ao mesmo tempo.

Este é o ponto de partida recomendado para qualquer engenheiro que queira trabalhar seriamente com o projeto.

Depois de dominar L0, as outras camadas (L1 Adapters, L2 Council, etc.) fazem muito mais sentido.

Este é o nível mais baixo e mais importante de compreensão do motor de destilação agêntica do Alembic.

Sem este entendimento, é muito difícil contribuir de forma segura e eficaz no projeto.