Operator Playbook + Practice Labs
Este documento cruza todas as camadas com os invariantes de arquitetura, checklists operacionais por role e labs práticos que tocam superfícies reais do repositório. É o material de referência para quem opera, estende ou audita o Alembic em produção.
Os 6 Invariantes de Arquitetura (load-bearing)
ModelAdapter.run() e retorna ModelRunResult (discriminado em ok). NUNCA lança. Ver: packages/contracts/src/model.ts:30 e packages/adapters/src/adapter-core.ts:23.2. Never-throws / Result<T> — Toda operação falível retorna
Result, não exception. Ver: packages/contracts/src/result.ts:20 e tryCatchAsync:60.3. Zod-first contracts — Todo tipo importante é schema Zod. O schema é a spec. Ver:
packages/contracts/src/ (todo).4. No upward dependencies — Grafo de camadas é acíclico (L-1 → L0 → L1 → L2 → L3 → L4), contracts como vocabulário compartilhado. Ver:
.factory/CODING_STANDARDS.md:16.5. Filesystem-as-truth — Stores são append-only + content-addressed JSONL. Re-run converge. Ver:
packages/etl/src/stores.ts e packages/swarm/src/store.ts.6. Safety gates are fail-closed — PII é redigido antes de qualquer adapter ou emit; toda chamada paga é budget-checked antes de rodar. Ver:
packages/etl/src/pii.ts (assertRedactedForEmit) e budget.ts.
Estes 6 invariantes são o que o Reviewer caça ativamente. Quebrar qualquer um é defeito, mesmo que typecheck.
Checklists por Role
• Toda mudança que toca model call deve preservar o contrato Result (nunca throw).
• Toda nova operação falível deve usar
tryCatchAsync ou equivalente.• Gates de PII e Budget nunca podem ser enfraquecidos.
• Commits atômicos + conventional + Co-Authored-By do Claude.
• Toda nova camada ou seam deve respeitar o grafo acíclico (sem upward deps).
• Novos stores devem ser append-only + content-addressed.
• Qualquer mudança em contracts exige atualização de todos os consumidores + testes.
• Antes de qualquer run real:
pnpm typecheck && pnpm build && pnpm -w test && pnpm detect.• Monitore
_alembic-residue.jsonl e custo por tier.• Qualquer sinal de canal privado com t1PiiBlocked > 0 é incidente de segurança.
• Claims de "barato e seguro" só podem ser FACT quando suportadas por evidência de runs reais (FunnelReport + ledger).
• Qualquer demo deve usar corpus pequeno + --offline primeiro.
6 Practice Labs (toquem superfícies reais)
- Adicione um novo adapter simples (ex: echo local). Registre via
createAdapterRegistry(registry.ts:89). Rodealembic distill ./corpus --offline. Confirme que o adapter foi usado e custo = 0. - Forçe um T3 park. Marque uma task com
irreversible: trueou tier T4. Rode um council T3 e observeparkedTierno VerificationReport + entrada no park ledger. - Quebre o PII gate intencionalmente (em teste). Injete um sinal de canal privado sem redação no residue e rode o funnel. Observe
t1PiiBlocked > 0no report. - Trace um run completo do Factory (em ambiente controlado). Pare após o Planner. Inspecione o JSON dentro de
<plan>. Continue e observe os worktrees criados. - Simule budget exhaustion. Rode um run com budget muito baixo em T2. Observe o tier degradar e o report refletir
t2BudgetBlocked. - Re-run convergente. Rode o mesmo distill offline duas vezes com o mesmo corpus. Confirme que o processed ledger só cresce na primeira vez e que os stores não duplicam registros (content-addressed).
Todos os labs acima tocam código real em packages/adapters, packages/council, packages/etl, packages/harness, .factory/ e apps/cli.
Como Verificar Este Material (verify)
pnpm detect # deve passar 0 anti-patterns em todo docs/ # Para cada lab acima, rode o comando correspondente e inspecione os artefatos gerados (residue, reports, worktrees, ledgers).
Common confusions: Achar que os invariantes são "boas práticas opcionais". Não — são load-bearing. Quebrar qualquer um (especialmente o never-throws waist ou os fail-closed gates) é defeito arquitetural, mesmo que o código rode.
Practice task: Pegue um dos 6 labs acima, execute-o em um ambiente controlado (use --dry-run onde possível), capture os artefatos gerados e anote em um learning-record qual invariante foi exercitado e como você confirmou que ele se manteve intacto.
Por que Este Playbook Existe
Os hotpaths e deep dives por camada ensinam como o sistema funciona. Este playbook ensina como operar e evoluir o sistema sem quebrar suas garantias fundamentais. Ele cruza todas as camadas com os invariantes que realmente importam em produção.
Qualquer pessoa que queira contribuir com o projeto, rodar o Factory em escala, ou fazer manutenção de longo prazo precisa internalizar estes 6 invariantes e os labs práticos acima. Este material é o elo que transforma conhecimento teórico em capacidade operacional real. Sem ele, mesmo quem domina as camadas individualmente pode causar regressões graves em produção.
Este playbook é o documento de "como não quebrar o que construímos" — e é tão importante quanto o código em si para a longevidade do projeto.
Sua existência garante que o conhecimento tácito sobre os invariantes não se perca com a rotatividade de pessoas ou agentes que trabalham no sistema.
Ele é a memória institucional viva do que realmente importa para manter o Alembic saudável e evoluindo de forma segura por anos.
Sem este tipo de material, projetos complexos como este acabam dependendo de "tribal knowledge" que se perde com o tempo — e isso é inaceitável para um sistema que pretende evoluir a si mesmo de forma autônoma.
Source Anchors (Evidência Direta)
| Arquivo:linha | Invariante / Conceito |
|---|---|
packages/contracts/src/model.ts:30 | The Waist (ModelRunResult) |
packages/adapters/src/adapter-core.ts:23 | Never-throws spine |
packages/contracts/src/result.ts:20 | Result<T> pattern |
.factory/CODING_STANDARDS.md:16 | No upward dependencies |
packages/etl/src/stores.ts | Filesystem-as-truth |
packages/etl/src/pii.ts | Fail-closed PII gate |
packages/etl/src/budget.ts | Fail-closed Budget gate |
packages/swarm/src/store.ts | Swarm journal + park ledger |