# Alembic Glossary

Terminologia canônica do motor de destilação agêntica Alembic (Zod-first, camadas L-1 a L4 + Factory). Usada em todos os estúdios, hot paths e learning records.

## Terms

**Result (discriminado)**:
Tipo união `ModelRunResult = ModelRunSuccess | ModelRunFailure` onde `ok: boolean` é o discriminante. Toda chamada de modelo (L1 adapters) **nunca lança** e sempre retorna este tipo. Invariante central do sistema.
_Avoid_: throw, exception, erro não tratado

**Funnel Tier (T0-T3)**:
Pipeline de 4 estágios de ETL barato sobre corpus privado. T0 = determinístico 100% ($0), T1 = LLM local, T2 = frontier batched, T3 = Council GO/PIVOT/NO-GO (~$0.03, gated por verifier). Re-run incremental por SHA-256.
_Avoid_: simple pipeline, ETL stages

**Verifier (maker-checker)**:
Gate T3+ no council. Força dissent explícito entre agentes. Se <3 agentes ou falha no consenso → NO-GO (fail-closed). Preserva divergência em vez de forçar consenso artificial. Tier 4 → humano obrigatório.
_Avoid_: simple judge, LLM evaluator

**ADW (Agentic Development Workflow)**:
Loop do swarm L3: Plan → (Implement → Review) paralelo em worktrees isolados → Fix → Publish (PR). Usado pelo factory para backlog GitHub `ready-for-agent`.
_Avoid_: simple agent loop, auto-coder

**ModelAdapter**:
Interface L1 pura: `{ id, run(input): Promise<ModelRunResult>, stream?, healthCheck? }`. 15+ implementações (anthropic, openai-compatible, local-cli, pi-dev, codex-oauth, circuit-breaker, retry, cost, offline...). Agnóstico de engine.
_Avoid_: SDK wrapper, direct API call

**Council (L2)**:
Engine de debate qualitativo + scoring quantitativo (0-10 por critério) + verifier. Produz veredito com dissent preservado. Usado em T3 e em factory review.
_Avoid_: single LLM call, majority vote

**Harness (L4)**:
Camada de orquestração que expõe o funnel (runFunnel) e bridge para clientes (CLI, API, etc.). Injeta ports (fs, adapters, stores) no kernel puro.
_Avoid_: main app, runtime entry

**Factory (software factory)**:
Runner em `.factory/run.ts` que executa planner + N workers paralelos em Docker sandboxes (claude-opus-4-8 por padrão). Usa prompts versionados + gates (typecheck, build, test, impeccable detect). Nunca push direto em main.
_Avoid_: simple codegen script, Cursor agent

**Content-addressed run**:
Todo run de modelo/ council/ swarm gera diretório determinístico baseado em SHA do input + config. Permite replay exato e caching.
_Avoid_: timestamped log dir

**Impeccable detect**:
Gate de design system e qualidade visual (`pnpm detect`). Roda no `docs/`. Enforça padrões de HTML autocontido, acessibilidade e anti-slop nos artefatos visuais.
_Avoid_: lint only, prettier

**Wiki LLM / WIKI_LLM**:
Substrato de dados privado (~330 GB, 128k pacotes) que alimenta o ETL. Nunca exposto diretamente a modelos (exclui Repos/Models e Repos/Prompts no T0). Fonte de LEARNINGS + BUSINESS SIGNALS.
_Avoid_: training data, RAG corpus