Playbook do operador

Saber pilotar um avião não é o mesmo que saber a checklist de pré-voo. Os hot paths te ensinaram a pilotar cada sistema; este playbook é a checklist que impede você de decolar com o trem de pouso travado.

Mapa de uma olhada: os 6 invariantes que o Reviewer caça — leia da esquerda para a direita, fileira de cima e depois a de baixo.

Estes seis são load-bearing: são exatamente o que o Reviewer caça ativamente. Quebrar qualquer um é defeito, mesmo que o typecheck passe. Comece pelo mapa de uma linha; cada cartão abaixo detalha o invariante e mostra a âncora arquivo:linha.

1 · The Waist (cintura, L1)

Toda chamada de modelo passa por ModelAdapter.run() e retorna ModelRunResult (discriminado em ok). Ela NUNCA lança. Essa única fronteira é a "cintura estreita" do sistema: o ponto por onde todo modelo entra.

2 · Never-throws / Result<T>

Toda operação falível retorna Result, não uma exception. O helper tryCatchAsync embrulha o que poderia lançar e devolve um Result. A falha vira dado que o chamador inspeciona — nunca um throw que sobe a pilha sem aviso.

// o contrato: falha é um valor, não um throw (packages/contracts/src/result.ts:20)
type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

const r = await tryCatchAsync(() => algoQuePodeFalhar());
if (!r.ok) return r;        // propaga o err — sem try/catch espalhado
usar(r.value);                // só aqui o sucesso é garantido

3 · Zod-first contracts

Todo tipo importante é um schema Zod. O schema é a spec: valida na borda, gera o tipo TypeScript e documenta o formato num só lugar (packages/contracts/src/). Não há "tipo de um lado, validação de outro" — é a mesma fonte de verdade.

4 · No upward dependencies

O grafo de camadas é acíclico: L-1 → L0 → L1 → L2 → L3 → L4, com contracts como vocabulário compartilhado por todos. Uma camada nunca importa de uma camada acima dela. É isso que mantém o sistema componível e testável.

5 · Filesystem-as-truth

Os stores são append-only e content-addressed (JSONL). Isso dá a propriedade que define o sistema: re-run converge — rodar de novo não duplica registros, porque o conteúdo é endereçado pelo próprio hash. O disco é a verdade; a memória é só cache.

6 · Safety gates são fail-closed

PII é redigido antes de qualquer adapter ou emit; toda chamada paga é budget-checked antes de rodar. "Fail-closed" significa: na dúvida, o gate recusa. assertRedactedForEmit bloqueia um emit não redigido; o budget guard degrada o tier antes de gastar demais.

A confusão mais comum é achar que os invariantes são "boas práticas opcionais". Não são. Eles são load-bearing — sustentam o sistema. Quebrar qualquer um (especialmente o never-throws da cintura ou os fail-closed gates) é defeito arquitetural, mesmo que o código rode.

O mesmo conjunto de invariantes é protegido por quatro lentes. A sua role define qual ângulo você defende. Use o explorador abaixo: cada aba acende a camada que aquela role mais toca e mostra a checklist correspondente.

As quatro responsabilidades em volta do mesmo núcleo — cada role guarda o invariante por um ângulo.

Saber os invariantes não basta; você precisa vê-los segurarem. Cada lab abaixo toca uma superfície real (packages/adapters, council, etl, harness, .factory/, apps/cli) e produz um artefato que prova o invariante. Onde der, use --dry-run / --offline.

O caminho fail-closed do lab de PII: o ramo "não redigido" leva ao bloqueio — e o bloqueio é a prova de sucesso.

Todos tocam código real em packages/adapters, packages/council, packages/etl, packages/harness, .factory/ e apps/cli.

Antes de qualquer run real, a role Operator roda a sequência completa de gates. Eles são fail-closed: se um falha, você não avança. Esta é a checklist de pré-voo do sistema.

# a checklist de pré-voo do Operator (rode da raiz do repo)
pnpm typecheck   # os tipos batem em todos os pacotes
pnpm build       # dependentes enxergam os .d.ts novos
pnpm -w test     # 284+ passam
pnpm detect      # 0 anti-patterns em todo o docs/ (impeccable)

# para cada lab da seção 5: rode o comando e inspecione o artefato
# (residue, reports, worktrees, ledgers).

Sinais que viram incidente

Cada invariante aponta para um arquivo real. Use esta tabela para provar qualquer afirmação deste playbook lendo a fonte — a disciplina é: nada sem âncora.

Avance os slides para fixar o playbook em seis ideias.

Três perguntas. A pontuação corre sozinha — responda todas para fechar a revisão.