Factory: a fábrica de software em sandboxes

Regra de ouro da fusão: o que é útil se internaliza — com a fonte citada. O campo description de packages/factory/package.json declara a origem, e o README dedica uma seção "Attribution": as primitivas de orquestração (run, createSandbox, createWorktree, os sandbox providers, o prompt resolver, os agent providers) são trabalho do Matt Pocock, sob MIT, com o copyright original retido verbatim em LICENSE.sandcastle.

// trecho real, não editado
"description": "Alembic software factory — orchestrates AI coding agents in
  isolated sandboxes. Vendored and adapted from @ai-hero/sandcastle
  (MIT, (c) Matt Pocock); see README.md."

A adaptação ao Alembic (README, §Attribution): pnpm em vez de npm e o layout de workspaces; os gates pnpm typecheck && pnpm build && pnpm test + impeccable detect docs/; commits convencionais; e o fluxo de main protegida — a fábrica abre PRs, nunca faz push em main. Os providers de sandbox em nuvem proprietários (Vercel, Daytona) não foram vendorizados: o Alembic usa o provider Docker, e aqueles exigiriam SDKs externos.

Pense como… comprar a planta de uma fábrica alemã e montá-la no seu terreno: a linha de montagem é do projetista original (e a placa na entrada diz isso), mas a voltagem, as normas e o portão de expedição são os do seu país. Onde quebra: uma fábrica física se compra uma vez; aqui o vendoring permite EVOLUIR a linha localmente — o código passou a ser de manutenção própria, com os testes do monorepo cobrindo cada peça.

Todo o resto se compõe a partir de UMA função: run (packages/factory/src/run.ts:360–371, com 3 overloads — Output.object devolve output: T tipado via extractStructuredOutput, Output.string devolve texto, sem output devolve o RunResult padrão). Você entrega um agente (claude code, codex, opencode, copilot, cursor, pi — os providers em AgentProvider.ts), um sandbox (sandboxes/docker.ts, podman.ts ou no-sandbox.ts) e um prompt (inline ou promptFile); a fábrica cria worktree + branch, roda o agente isolado e sincroniza o resultado de volta.

Duas decisões de engenharia merecem zoom: (a) estratégia de branch derivada do isolamento — sandbox isolated ⇒ merge-to-head; a estratégia head é RECUSADA com provider isolado (run.ts:386–400: "head branch strategy is not supported with isolated providers") — um agente isolado nunca escreve direto na sua árvore; (b) fan-out por fork de sessão — RunResult.fork(prompt) re-executa a partir da sessão capturada do pai, com id de sessão próprio; forks concorrentes exigem branches distintos (run.ts:339–352, nota do ADR 0018).

O contrato compartilhado das fases da fábrica vive em @alembic/contracts: factoryPhaseSchema (packages/contracts/src/domain.ts:99–108) — um enum Zod de 7 fases, "from opportunity discovery through shipped product" (domain.ts:95–98).

// trecho real, não editado
export const factoryPhaseSchema = z.enum([
  'discover',
  'validate',
  'design',
  'plan',
  'build',
  'review',
  'ship',
]);
export type FactoryPhase = z.infer<typeof factoryPhaseSchema>;

Onde ele entra no distill --from/--to

O comando alembic distill aceita --from e --to exatamente com esse vocabulário: distillArgsSchema declara from: factoryPhaseSchema.default('discover') e to: factoryPhaseSchema.default('review') (apps/cli/src/args.ts:74–75) — "from/to bound the phase window of the funnel" (doc do schema, args.ts:62–63). Um valor fora do enum falha o parse na borda (custo $0, nada roda). O mesmo enum alimenta alembic status, que imprime a esteira inteira: phases: factoryPhaseSchema.options → discover -> validate -> design -> plan -> build -> review -> ship (apps/cli/src/commands.ts:464, 472).

O pacote também expõe o binário alembic-factory (package.json, campo bin) e entrypoints dedicados por sandbox (./sandboxes/docker, ./sandboxes/podman, ./sandboxes/no-sandbox — campo exports), então um scaffold escolhe só o provider que usa, sem carregar os demais.