Layer L3: @alembic/swarm — O Orquestrador 3-Tier
Esta camada implementa orquestração depth-bounded, dependency-gated, com suporte a worktree isolation, background detached workers e park para T4. É o mecanismo usado pelo Factory para rodar ADW em paralelo de forma segura e resumível.
Orchestrator (orchestrator.ts)
// orchestrator.ts:31
/** The 3-tier, depth-bounded orchestrator: orchestrator → lead → worker.
* Hard rules:
* 1. MAX_DEPTH = 2 (worker is leaf)
* 2. Dependency-gating via TaskQueue
* 3. T4 park for irreversible/legal/security/manual tasks
* Every transition is journaled in the Store. Fully resumable. */TaskQueue & Dependency Gating (queue.ts)
// queue.ts:15
/** A dependency-gated task queue.
* A task is `ready` only when every id in `dependsOn` has reached `done`.
* Pure in-memory; durability is the Store's job. */Tipos principais em types.ts:43-64 (taskStatus, parkReason) e taskSpecBaseSchema:77-98.
Execution Model
- Worker leaf: adapter.run ou subprocess real (command) → report file protocol (.inprogress → atomic .complete/.failed)
- Lead: fan-out de subtasks como sub-run recursivo (depth-bounded)
- Isolation: withWorktree + isolate flag (dedicated branch + port)
- Background: spawnBackgroundCommand (detached, sobrevive ao pai)
worker.ts, process.ts, worktree.ts, background.ts
Como Verificar Esta Camada (verify)
pnpm test packages/swarm # Foco: # - orchestrator.test.ts # - queue.test.ts (dependency gating) # - park.test.ts, reward.test.ts # - worktree.test.ts, background-entry.test.ts
Common confusions: Achar que "swarm é só orquestrador simples". Não — tem journal completo para resume, park ledger separado, depth bounding rígido, e dois modos de execução (adapter vs real command subprocess).
Practice task: 1. Leia orchestrator.ts:31-46 (comentário de arquitetura). 2. Leia types.ts:43-64 (estados + park reasons). 3. Rode um swarm pequeno e inspecione o journal no store. 4. Marque uma task como irreversible e observe o park. 5. Compare um run com e sem `isolate: true`.
Deep Line-by-Line
orchestrator.ts:31-46 — O comentário de arquitetura é o melhor resumo do design: 3-tier, depth-bounded (MAX_DEPTH=2), dependency-gating, T4 park, journal no Store, resumable.
queue.ts:15-22 — TaskQueue é pura (in-memory). Durabilidade é responsabilidade do Store. Gating é "todos os dependsOn em 'done'".
worker.ts + process.ts — Protocolo de report file (.inprogress → atomic rename). Suporte a adapter.run ou subprocess real (command).
worktree.ts + background.ts — Dois mecanismos de isolamento: git worktree dedicado e detached background process.
Source Anchors (Evidência Direta)
| Arquivo:linha | Conceito |
|---|---|
/packages/swarm/src/orchestrator.ts:31 | 3-tier orchestrator architecture |
/packages/swarm/src/types.ts:32 | MAX_DEPTH = 2 |
/packages/swarm/src/queue.ts:15 | dependency-gated TaskQueue |
/packages/swarm/src/park.ts | classifyPark + T4 reasons |
/packages/swarm/src/worktree.ts | isolate + git worktree |
/packages/swarm/src/background.ts | detached background workers |
/packages/swarm/src/store.ts | journal + checkpoint + park ledger |
Por que L3 Swarm é Importante
É a camada que permite ao Factory rodar múltiplos implement+review em paralelo de forma segura, isolada e resumível. Sem ela, o ADW não seria confiável em escala.
Entender linha a linha o orchestrator, a queue com dependency-gating, o park, o worktree isolation e o background dispatch é entender como o projeto consegue fazer evolução paralela sem quebrar o repositório.
Esta é a camada que transforma o "plano" do Factory em execução real, distribuída e auditável. O journal no Store + o sistema de park + o suporte a worktree e background são o que permitem que o sistema evolua a si mesmo de forma confiável.
Sem o Swarm, o Factory seria apenas um orquestrador ingênuo de processos. Com ele, vira um sistema de execução agêntica com garantias fortes de isolamento, resumibilidade e segurança.
Deep Line-by-Line Analysis
orchestrator.ts:31-46 — O comentário de arquitetura é o documento de design mais importante da camada. Ele define explicitamente as três regras duras: depth bound, dependency gating e T4 park. O Store é a fonte de verdade para journal, checkpoint e park ledger.
types.ts:32 — MAX_DEPTH = 2. Worker (depth 2) é leaf e não pode spawnar. Isso é o que impede recursão infinita.
queue.ts:15-22 — A TaskQueue é pura (in-memory). Ela só responde "quais tasks estão ready agora?". Toda durabilidade e resume vem do Store.
worker.ts + process.ts — O protocolo de report file é simples mas poderoso: o worker cria .inprogress, faz o trabalho, e faz rename atômico para .complete ou .failed. O orquestrador só precisa poll o diretório de reports.
worktree.ts + background.ts — Dois mecanismos complementares de isolamento. Worktree dá branch + port dedicado para tarefas que precisam de ambiente limpo. Background permite workers que sobrevivem à morte do processo pai (útil para tarefas longas).
Esta combinação de mecanismos é o que permite ao Factory executar múltiplos agentes em paralelo de forma segura e auditável.
O design do Swarm mostra maturidade de engenharia de sistemas distribuídos aplicados a agentes: journal, checkpoint, isolamento, e separação clara entre orquestração e execução.
Esta camada é fundamental para qualquer sistema que queira fazer evolução paralela de código de forma segura e rastreável.
O Swarm representa um dos pontos mais avançados do projeto em termos de arquitetura de execução agêntica distribuída.
Compreender profundamente o Swarm é essencial para quem deseja contribuir com melhorias no Factory ou criar novos padrões de execução paralela no ecossistema Alembic.
Esta deep dive fecha a visão das principais camadas de execução do projeto (junto com L0, L1 e L2).
O próximo passo natural seria L4 Harness, que é a camada que expõe todo esse poder para CLI, HTTP, MCP e outros clientes.
Com o L3 Swarm bem compreendido, o sistema de execução paralela do Alembic fica muito mais claro e poderoso.
Esta é uma das camadas mais avançadas do projeto e representa um passo importante na direção de sistemas de agentes verdadeiramente autônomos e seguros.
O Swarm + o Factory juntos formam um dos sistemas mais sofisticados de auto-evolução de código que existem atualmente.