PATTERN: 04-CODE-UNDERSTANDING + 13-FLOWCHART + 16-IMPLEMENTATION-PLAN (do html-effectiveness gallery interno do visual-teach-studio)
Evidence Inventory + Source Map
Missão: Dominar a estrutura exata de 235 arquivos .ts do motor de destilação agêntica. Cada número, path e fluxo é derivado de leitura direta (subagentes explore + HANDOFF + filesystem). Fatos rotulados. Base para todos os estúdios linha-a-linha.
Resumo Executivo (4 gates + 235 arquivos)
235 arquivos .ts em packages/*/src + apps/cli
7 pacotes @alembic/* (contracts é o spine Zod-first)
1 CLI + 1 Factory runner (.factory/run.ts)
4 gates obrigatórios: pnpm typecheck • build • test (284+) • detect (impeccable)
Como construído (FACT)
3 subagentes explore paralelos (48–60 tool calls cada) + leituras manuais de HANDOFF.md, todos package.json, pnpm-workspace, turbo.json, .factory/*, contracts model/result, harness funnel/bridge, adapters registry/core, council debate/verifier, etl pipeline/pii/stores, factory run + prompts, swarm orchestrator, cli commands. Dados de 2026-06-01 HEAD.
3 subagentes explore paralelos (48–60 tool calls cada) + leituras manuais de HANDOFF.md, todos package.json, pnpm-workspace, turbo.json, .factory/*, contracts model/result, harness funnel/bridge, adapters registry/core, council debate/verifier, etl pipeline/pii/stores, factory run + prompts, swarm orchestrator, cli commands. Dados de 2026-06-01 HEAD.
1. Inventário Completo por Pacote (Evidence com paths exatos)
| Pacote (src/) | # .ts | Responsabilidade Principal (subagente) | Arquivos Críticos (paths absolutos chave) | Cross-deps |
|---|---|---|---|---|
| @alembic/contracts | 6 | Narrow waist: ModelRunInput/Result discriminado (ok), Tier, Registry, WikiPackage, BusinessSignal, Learning, Result helpers, tryCatchAsync. Puro (só Zod). | model.ts (ModelRunInput + TokenUsage), result.ts, tier.ts (T0-T4 + escalate), registry.ts, domain.ts, wiki.ts, index.ts | apenas zod |
| @alembic/adapters | 25 | L1: ModelAdapter.run → Result (nunca lança). Registry + router + 15+ providers (anthropic, openai-compatible, local-cli, pi-dev, codex-oauth, offline) + cross (retry, circuit-breaker, cost, http, token-store, clock, logger, errors). | registry.ts, adapter-core.ts + tests, retry.ts + test, circuit-breaker.ts + test, cost.ts + test, anthropic.ts, openai-compatible.ts, local-cli.ts, pi-dev.ts, codex-oauth.ts, http.ts, errors.ts, router.ts, token-store.ts, offline.ts + test | @alembic/contracts (24 imports) |
| @alembic/council | 11+tests | L2: Debate (runDebate, phases, contrarian last), scoring 5 eixos 0-10 + thresholds (GO≥7), Verifier (maker-checker + 3+ quorum + dissent), VerifierPanel (faithfulness + domain lenses), ContextPack, Consensus (fail-closed MIN=3), Board YAML. | debate.ts, verifier.ts, verifier-panel.ts, scoring.ts, consensus.ts, context-pack.ts, board.ts, response.ts, index.ts + 7 tests | contracts + adapters (debate) + yaml |
| @alembic/etl | 17+tests | L0/T0-T3 funnel: runT0Pipeline (walkCorpus excluindo Models/Prompts, dedupe SHA, validate, score 6 eixos, residue), priors (FAMILY_PRIORS → tier routing), pii.ts (redact + assertRedactedForEmit gate para canais privados), stores (append-only content-addressed JSONL: opportunity-graph + learnings), budget guard, FsPort injectable, jsonl streaming, dedupe ledger. | pipeline.ts, pii.ts, stores.ts, priors.ts, score.ts, validate.ts, dedupe.ts, fs-port.ts, jsonl.ts, budget.ts, index.ts + 5 test/*.ts + fixtures/corpus | contracts (pesado) |
| @alembic/harness | 16+tests | L4: runFunnel (T0-T3 + council + budget/PII gates → FunnelReport), bridge (distillAndMarket, marketing-factory), HarnessCore (fanout council/swarm), thin transports (cli/http/sse/mcp), manifest-store (append/read content-addressed), events. | funnel.ts + test, bridge.ts + test, core.ts, server.ts + test, mcp.ts + test, cli.ts, manifest-store.ts + test, http.ts, events.ts, logger.ts, index.ts | contracts + adapters + council + etl + swarm + marketing-factory (38 imports) |
| Componente | # | Responsabilidade (subagente) | Arquivos Críticos | Notas |
|---|---|---|---|---|
| @alembic/swarm | 22 | L3: runSwarm (orchestrator com TaskQueue dep-gated, journal append-only para resume/recover, MAX_DEPTH=2, lead vs leaf workers, park por tier/T4/irreversível, PARL reward, withWorktree isolate, spawnBackgroundCommand detached, runWorker/process + report protocol .inprogress→.complete). | orchestrator.ts, queue.ts, worker.ts, process.ts, store.ts, types.ts (Zod TaskSpec), park.ts, reward.ts, background.ts, worktree.ts, monitor.ts, index.ts | Usado por factory para ADW real + harness |
| @alembic/factory (104+ .ts) | 104+ | Software factory (vendored/adapted de sandcastle MIT): run() + orchestrate (Effect-heavy), SandboxFactory (docker/podman bind-mount worktree isolado), AgentProvider (claudeCode/codex etc com stream parse), PromptResolver/Preprocessor/ArgSubst (!cmd + {{}} guards), Orchestrator loop (maxIters, parallel), Display, Output structured extraction. Sem deps runtime @alembic/* (só effect/zod/clack). | run.ts, Orchestrator.ts, SandboxFactory.ts + sandboxes/docker.ts, AgentProvider.ts, PromptResolver.ts, templates/ (5 scaffolds com parallel-planner-with-review), cli.ts/main.ts, index.ts, global.d.ts | Entry: pnpm factory (usa .factory/run.ts + prompts versionados) |
| .factory (runner + prompts) | 1 .ts + 5 .md | Loop ADW concreto sobre GitHub ready-for-agent (plan via gh → parallel implement/review em Docker sandboxes → publish PR). Gates completos antes de commit/PR. Nunca force-push main. | run.ts, plan-prompt.md (emite JSON | Invariantes idênticos ao engine |
| apps/cli | 7+tests | Superfície fina: runDistill (build registry offline/live, preflight, runFunnel do harness, render report), runStatus, runIngest. Tudo via Result (never throw). Zod args + env. | commands.ts (distill/status/ingest), args.ts (Zod + parse), config.ts (liveRegistryOptions + preflight), index.ts (bin), logger.ts + e2e/command tests | Depende harness + etl + adapters + contracts |
| Root monorepo | — | Turbo (build/typecheck/test order), pnpm workspace, vitest workspace (exclui factory heavy tests), tsconfig base (strict + paths @alembic/*), scripts factory/detect. | package.json, pnpm-workspace.yaml, turbo.json, tsconfig*.json, vitest*.ts, .factory/run.ts (invocado via tsx) | Factory excluído de vitest root |
2. Arquitetura em 6 Camadas — Diagrama (SVG inline)
SVG ensina o fluxo de dados + camadas (não decorativo). Cintura estreita: toda chamada de modelo passa por ModelAdapter.run → Result discriminado (ver model.ts:30 e adapter-core.ts).
3. Source Map — Ordem de Leitura Recomendada (não comece aqui)
- HANDOFF.md (visão completa + 4 invariantes) +
packages/contracts/src/model.ts:30(ModelRunInput) +result.ts(narrow waist). apps/cli/src/commands.ts:24(runDistill → runFunnel) +config.ts.packages/harness/src/funnel.ts+bridge.ts(L4).packages/adapters/src/registry.ts+adapter-core.ts(L1 contrato universal + runWithGuards).packages/council/src/debate.ts+verifier.ts+verifier-panel.ts(L2 com dissent forçado).packages/etl/src/pipeline.ts+pii.ts+stores.ts(T0 + redaction + append-only)..factory/run.ts:22+ prompts (ADW real usando o engine para evoluir a si mesmo).- Não comece aqui: docs/ (output visual), node_modules/, dist/, terraform (detalhe deploy), .turbo.
4. Como Verificar Este Inventário (Gates + Validator)
pnpm install pnpm typecheck pnpm build pnpm -w test # 284+ passed pnpm detect # impeccable no docs/ (inclui este HTML) # Validator oficial visual-teach-studio (exige 4+ sections, 1+ SVG, 1+ interaction, 6+ anchors, verify/confusions/practice) python3 /Users/acf/.codex/plugins/visual-teach-studio/skills/visual-teach-studio/scripts/validate_visual_teach_output.py \ /Users/acf/Documents/Projects/appfy/alembic/docs/learn-alembic-complete
Common confusions: Achar que "factory é só código de exemplo" (é o ADW rodando em produção sobre o próprio engine) ou que "council é só prompt" (tem verifier programático com oráculos + quorum + parked T4).
5. Practice Task (toque o código real)
Tarefa: Rode pnpm factory --help (ou inspecione .factory/run.ts:22) e identifique onde o planner emite o JSON <plan> que vira branches factory/issue-N. Depois abra packages/harness/src/funnel.ts e localize a chamada para council em T3. Anote as linhas.
Critério de sucesso: Você consegue apontar 3 arquivos exatos (com linha aproximada) responsáveis por: (1) nunca lançar em chamada de modelo, (2) redaction de PII antes de emit, (3) fail-closed no verifier T3+.
Ao completar, registre em learning-records/00xx-source-map.md.