Result (discriminado) L0
União `ModelRunResult = Success | Failure` com discriminante `ok: boolean`. Toda operação que pode falhar (especialmente chamadas de modelo) nunca lança e sempre retorna este tipo.
contracts/result.ts:20 (def + tryCatchAsync:60)
contracts/model.ts:30 (ModelRunResult)
adapter-core.ts:60 (guardedAttempt → Result)
operator-playbook.html (invariante #2)
Confusão comum: "Posso dar throw dentro do adapter e tratar no chamador". Não. O contrato público é Result; qualquer exceção interna é convertida em failure tipado antes de subir.
Prática: Abra contracts/result.ts:20 e adapters/adapter-core.ts:82-100. Escreva um teste que força um attempt a lançar → confirme que o Result final é failure e o circuit-breaker recebeu feedback.
ModelAdapter (narrow waist) L1
Interface mínima: `{ id, run(input: ModelRunInput): Promise<ModelRunResult> }`. 8+ implementações (cliproxyapi, anthropic, local, offline, retry, breaker, cost...). Todo o sistema (funnel, council, swarm, factory) fala apenas com esta interface.
contracts/model.ts:30 (def)
adapter-core.ts:23-100 (runWithGuards spine)
registry.ts:89 (createAdapterRegistry)
router.ts:53 (pickAdapter, sem fallback silencioso)
Confusão: "Vou chamar o SDK direto para economizar uma camada". Quebra a cintura, perde retry/breaker/cost accounting, e viola a invariante de nunca lançar.
Prática: Adicione um provider fake no registry e rode um distill offline. Trace a chamada até o Result retornado.
runWithGuards L1
Spine reutilizável em adapter-core.ts que transforma uma "tentativa única" em um ModelAdapter compliant: validação → circuit-breaker → attempt → retry (com backoff) → feedback no breaker → Result (nunca throw).
adapter-core.ts:23-100 (full flow)
adapter-core.ts:82-100 (guardedAttempt)
layer-l1-adapters.html (diagrama + explicação linha a linha)
Confusão: "O retry é responsabilidade do provider". Não. O retry e o breaker são cross-cutting e vivem no guard; o provider só implementa `attempt`.
Prática: Force um 429 no provider fake e observe o retry + breaker half-open funcionando (ver adapter-core.test.ts).
Funnel Tier (T0-T3) L0
Pipeline de ETL barato em 4 estágios. T0 = determinístico 100% ($0, SHA-256 incremental, exclui Models/Prompts). T1 = LLM local. T2 = frontier batched. T3 = Council GO/PIVOT/NO-GO (~$0.03, gated por verifier).
harness/funnel.ts:83 (runFunnel)
etl/pipeline.ts:27 (runT0Pipeline)
hotpath-cli-funnel.html (sequência completa com custos)
Confusão: "T2 toca todo o corpus". Falso. Frontier só vê shortlist de T1 (centenas de itens, não 128k).
Prática: Rode `alembic distill ... --offline` sobre o fixture e conte quantos itens cada tier processou.
emitSafeSignal + assertRedactedForEmit Cross
Gate fail-closed de PII. Qualquer sinal de canal privado (whatsapp, discord, skool, circle) passa por redactSignal + assertRedactedForEmit ANTES de qualquer chamada de modelo ou write em store.
etl/pii.ts (assertRedactedForEmit + PRIVATE_CHANNELS)
harness/funnel.ts:243 (emitSafeSignal)
hotpath-cli-funnel.html (PII gate no T1)
Confusão: "A redação acontece depois da chamada T1". Não — é feita no extractionInput, antes do adapter.run.
Prática: Injetar um pacote com PII plantada no fixture e confirmar que o sinal emitido no store não contém dados sensíveis.
Verifier (maker-checker) L2
Gate T3+ que separa debate (maker) de verificação independente (checker). Usa oráculos puros (ClaimOracle) sobre evidência. Se < MIN_VALID_AGENTS ou falha em qualquer lente → NO-GO ou park T4.
council/verifier.ts:19-84 (ClaimOracle + oracles)
council/verifier-panel.ts:21-44 (3 lentes)
hotpath-council-t3.html (fluxo completo)
Confusão: "O council é só prompt de debate". Falso — o verifier é código determinístico que pode vetar o debate inteiro.
Prática: Abra verifier-panel.test.ts e rode o caso de GO com evidência zero → observe o veto de faithfulness.
preserve-dissent veto + Verifier Panel L2
3 lentes (coerência, faithfulness, domínio). Quorum 2/3 + qualquer reject HARD (especialmente faithfulness ou evidência-zero) bloqueia emissão. Dissent é preservado, não suprimido.
verifier-panel.ts:21-44 (lenses + veto)
verifier-panel.ts:40 (FAITHFULNESS floors)
layer-l2-council.html (explicação + testes)
Confusão: "Quorum resolve tudo". Não — o veto de dissent é hard e prevalece sobre quorum.
Prática: Simule no council um GO com conf < 0.5 em faithfulness e veja o painel rejeitar.
MAX_DEPTH = 2 L3
Limite estrutural de profundidade no orquestrador 3-tier. Orchestrator = depth 0, Lead = 1, Worker = 2 (leaf). Worker nunca pode spawnar subtarefas. Previne explosão e recursão infinita.
swarm/types.ts:32 (MAX_DEPTH)
swarm/orchestrator.ts:31-46 (enforcement)
layer-l3-swarm.html (diagrama + rationale)
Confusão: "Podemos ter workers aninhados arbitrariamente". Não — a constante é hard e checada em canSpawn.
Prática: Tente criar uma tarefa com subtasks em depth 2 e observe o fail-closed.
Journal-before-action + replayInto L3
Todo estado de tarefa é journalado em append-only antes da execução. Em crash, `replayInto` reconstrói o queue a partir do journal + park-ledger. Garante at-least-once sem double-spend em adapters pagos.
swarm/store.ts (journal + checkpoint)
swarm/orchestrator.ts (replayInto)
hotpath-factory-adw.html + layer-l3-swarm.html
Confusão: "O resume re-executa tudo". Não — tarefas terminais são puladas; apenas órfãs em "running" voltam para ready.
Prática: Mate um worker mid-run e rode resume. Observe que tarefas já done não re-executam.
withWorktree (isolation + teardown) L3
Primitivo de resource-safety: cria worktree + branch, executa o worker dentro, e faz teardown garantido no finally (sucesso, erro ou throw). Vazamento de worktree é erro grave.
swarm/worktree.ts (withWorktree)
swarm/process.ts (runProcess endurecido)
layer-l3-swarm.html (exemplo de uso em command workers)
Confusão: "Em caso de erro o cleanup pode falhar". O design engole erro de cleanup para não mascarar o sucesso do trabalho principal.
Prática: Rode um task com isolate:true e confirme que o worktree é removido mesmo se o comando falhar.
Background (detached) workers + report-file L3
Workers que sobrevivem à morte do pai. O orchestrator coordena apenas via arquivo de report (`.inprogress` → `.complete`/`.failed`). Usado para comandos longos que não devem bloquear o slot.
swarm/background.ts (dispatcher + poll)
swarm/background-entry.ts
layer-l3-swarm.html (protocolo completo)
Confusão: "É fire-and-forget". Não — o orchestrator faz poll do report-file e re-attach no resume.
Prática: Lance um background task, mate o processo pai, rode resume e veja o worker re-anexar.
ADW (Agentic Development Workflow) Factory
Loop meta: Planner (gh issues) → N implementers paralelos em Docker sandboxes → Reviewer adversarial → Publisher (abre PR). Gates typecheck/build/test/impeccable antes de PR. Nunca push direto em main.
.factory/run.ts:22-153 (loop completo)
packages/factory/src/Orchestrator.ts
hotpath-factory-adw.html + CODING_STANDARDS.md
Confusão: "É só um template de Cursor". Falso — é o sistema que constrói o Alembic usando o próprio Alembic (meta).
Prática: Rode `pnpm factory` (com .env) e observe um ciclo completo planner → implementer → reviewer.
Budget fail-closed Cross
Antes de toda chamada paga (T2/T3), o budget é checado. Se excedido → fail-closed imediato (sem chamada). Spend é metrado via registry mesmo quando o adapter não retorna costUsd.
harness/funnel.ts (budget guard)
etl/budget.ts
operator-playbook.html (lab 6: estourar budget)
Confusão: "Override de modelo barato bypassa o cap". Não — pricing sempre usa o tier do registry (pricingModelId), nunca o override.
Prática: Rode funnel com budget:0 e confirme que T2/T3 não executam e o run é marcado como budget-exhausted.
HarnessCore (transport-neutral) L4
Núcleo de orquestração que expõe runFunnel + EventBus. Clientes finos (CLI, HTTP/SSE server, MCP RO, console) apenas injetam adapters/stores e consomem o bus. O kernel não sabe como é chamado.
harness/core.ts:41-50 (HarnessCore)
harness/funnel.ts:83 (runFunnel)
harness/server.ts + mcp.ts (transportes)
Confusão: "O servidor HTTP é o coração". Não — o core é puro; o server é apenas um adaptador fino de transporte.
Prática: Instancie HarnessCore com adapters fake e chame runFunnel diretamente (sem CLI nem HTTP).
distillAndMarket bridge L4
Composição `runFunnel` → `runMarketingBatch` (sinais verified-GO, PII-safe). Persiste cada AssetsManifest em store append-only content-addressed (`Marketing/manifests.jsonl`).
harness/bridge.ts:11-28
harness/manifest-store.ts
marketing-factory/generate.ts (CopyModel seam)
Confusão: "Marketing roda só no produto". Não — o bridge já existe no harness e permite que o próprio engine gere criativos antes de entregar para FounderOS.
Prática: Rode distillAndMarket offline com budget suficiente e inspecione o manifests.jsonl gerado.
Content-addressed run Cross
Todo run (model, council, swarm, marketing) gera diretório/arquivos determinísticos baseados em hash do input + config. Permite replay exato, caching e convergência de re-runs.
etl/stores.ts (appendStoreRecord + hashOf)
harness/manifest-store.ts (dedupe por sha256)
swarm/store.ts (journal por runId)
Confusão: "IDs são UUIDs aleatórios". Muitos são content-derived (manifestId, alguns run dirs) para garantir idempotência.
Prática: Rode o mesmo distill duas vezes com dryRun:false e confirme que o manifestId é idêntico.
priorFor + routesToResidue L0
Heurística determinística T0 que atribui prior de sinal por família (Transcripts 0.9, WhatsApp 0.7, Unknown 0.1) e decide se o item vai para residue (baixa prioridade) ou para extração T1.
etl/priors.ts (priorFor + routesToResidue)
layer-l0-contracts-etl.html (explicação + testes)
Confusão: "Tudo vai para o LLM". Não — T0 já descarta ou baixa prioridade de 70-90% do volume antes de qualquer chamada paga.
Prática: Inspecione o residue gerado por um run T0 e veja quais famílias dominam.
Debate phases + contrarian-last L2
Ordem serial de fases no debate (optimist → analyst → pessimist/contrarian por último). O contrarian vê tudo que foi dito antes e é obrigado a dissentir. Preserva diversidade de pensamento.
council/debate.ts:31-159 (phases + buildVote)
debate.ts:108-159 (fluxo de membro + priorPhases)
hotpath-council-t3.html
Confusão: "Todos os membros rodam em paralelo e só depois se olham". Não — o contrarian é último por design e recebe o histórico completo.
Prática: Leia debate.ts:108-159 e simule um round com 3 membros; observe o contrarian recebendo priorPhases.
CODING_STANDARDS (invariantes de código) Cross
Regras duras: Result never-throws, no `any`, funções puras ≤50 loc, early return, named exports only, 2 spaces, single quotes, conventional commits + Co-Authored-By. Reviewer caça violações ativamente.
.factory/CODING_STANDARDS.md
.factory/run.ts:95 (Reviewer usa o padrão)
hotpath-factory-adw.html
Confusão: "É só estilo". Não — quebrar Result ou usar any é defeito de arquitetura, não de formatação.
Prática: Rode o reviewer mentalmente sobre um PR seu: quantas linhas violam o ≤50 loc ou o "no upward dep"?
Impeccable detect (gate de design) Cross
Comando `pnpm detect` (impeccable@2.3.2) que roda em todo `docs/`. Reprova low-contrast, tiny text, em-dash overuse, side-tabs, repeated kickers, roboto, etc. É o "council visual" do projeto.
package.json (script detect)
HANDOFF.md (gate de design)
docs/ (todos os 11 artefatos passaram)
Confusão: "É só lint de HTML". Não — é a constituição visual que garante que todo artefato didático seja legível, acessível e anti-slop.
Prática: Rode `pnpm detect` após editar qualquer .html em docs/ e corrija até exit 0.