Contratos e trade-offs

A interface DeskPilotRepository (em src/domain/repository.ts) é o contrato que separa domínio de armazenamento. Ela declara applyIdempotentCommand como um método que deve produzir o mesmo resultado gravado quando chamado duas vezes com o mesmo commandId — essa garantia não é opcional nem específica do Postgres; a implementação em memória precisa satisfazê-la também, e o mesmo arquivo de teste (test/api/api.test.ts) roda contra ela.

A escolha de isolamento de tenant tem duas camadas deliberadamente redundantes:

• Camada de aplicação: todo método de PgRepository abre uma transação, executa SELECT set_config('app.tenant_id', $1, true) (o equivalente parametrizado de SET LOCAL app.tenant_id = $1 — que não aceita bind parameters) e só então roda a query real, escopada WHERE tenant_id = $1.
• Camada de banco: migrations/0001_init.sql habilita row-level security em todas as tabelas com escopo de tenant e cria uma política tenant_isolation que compara tenant_id ao mesmo current_setting('app.tenant_id', true).

alter table tickets enable row level security;
-- (users, suggestions, audit_events e applied_commands recebem o mesmo alter)

drop policy if exists tenant_isolation on tickets;
create policy tenant_isolation on tickets
  using (tenant_id = current_setting('app.tenant_id', true))
  with check (tenant_id = current_setting('app.tenant_id', true));

Por que duas camadas para a mesma garantia? Porque a documentação do PostgreSQL é explícita sobre um detalhe fácil de esquecer: "the table's owner is typically not subject to row security policies" (PostgreSQL, Row Security Policies, acesso 2026-09-28). Se o time de migração testar RLS conectado como dono — o papel mais comum durante desenvolvimento — a política nunca vai falhar, mesmo quebrada. Por isso migrations/0001_init.sql cria um papel separado, deskpilot_app, sem BYPASSRLS e sem posse de nenhuma tabela, e é só com esse papel que test/flow/rls.test.ts roda. Um dos cinco testes ali existe só para provar o caso oposto: sem app.tenant_id definido, uma sessão autenticada como deskpilot_app não vê nenhuma linha de nenhum tenant — a mesma documentação explica por quê ("If no policy exists for the table, a default-deny policy is used"), e a ausência de valor na sessão produz o mesmo efeito prático.

O trade-off do lado da idempotência é mais estreito do que parece à primeira vista. A documentação da Stripe sobre requisições idempotentes (acesso 2026-09-28) descreve um contrato mais rico do que este exemplo implementa: a chave de idempotência da Stripe salva o corpo e o código de status da primeira requisição — inclusive erros 500 — e pode ser descartada automaticamente depois de, no mínimo, 24 horas. A tabela applied_commands deste capítulo não expira, não devolve o corpo original byte a byte, e não tem escopo por chave de API. É suficiente para provar a propriedade que este capítulo pede — retry não duplica atribuição nem evento —, mas não é uma implementação de idempotência de propósito geral, e um leitor que for construir isso para uma API externa real deveria ler o contrato específico dessa API, não copiar esta tabela.

As quatro falhas que este capítulo precisa resolver, com sintoma, causa e resposta

Falha 1 — Demo sem persistência. Sintoma: o fluxo funciona perfeitamente ao vivo, mas qualquer restart (do processo, da aba, do laptop) apaga o progresso. Causa: o estado inteiro vive em variáveis de UI ou num array em memória do processo Node, nunca chega a um banco durável. Resposta: PostgreSQL real, com migração versionada (migrations/0001_init.sql) e seed reprodutível (seed/seed.ts); verification.md documenta um teste específico — triagem e atribuição via HTTP, depois docker restart series-ai-pe04-pg, depois releitura direta pelo repositório — confirmando que o ticket e os dois eventos de auditoria sobrevivem ao restart do container.

Falha 2 — Autorização só na UI. Sintoma: trocar o id na URL, ou chamar a API diretamente pulando a tela, deixa um tenant ler ou mudar o ticket de outro. Causa: a checagem de "isso é seu tenant?" existe só no componente React que decide o que renderizar, nunca no handler que de fato executa a query. Resposta: duas camadas independentes, descritas acima — filtro tenant_id = $1 em toda query do PgRepository, mais política RLS no banco testada contra um papel que não é dono da tabela. O teste tenant B cannot read tenant A's ticket by id devolve 404, não 403: a existência do recurso para o tenant errado também não é revelada.

Falha 3 — Seeds sensíveis. Sintoma: o script de seed usado "só para testar localmente" contém nomes, e-mails ou telefones reais copiados de uma planilha de cliente, ou uma senha fixa commitada no repositório que depois aparece num ambiente que não deveria ter acesso a ela. Causa: conveniência de curto prazo — é mais rápido copiar um dado real do que inventar um sintético plausível, e senha fixa evita configurar variável de ambiente. Resposta: seed/seed.ts só contém identificadores sintéticos (tenant-a, agent-b1) sem nenhum campo de nome, e-mail ou telefone; a senha do papel deskpilot_app é lida de DESKPILOT_APP_PASSWORD, nunca escrita no .sql (o placeholder :'deskpilot_app_password' em migrations/0001_init.sql é substituído em tempo de execução por migrate.ts); .env.example documenta as variáveis sem nenhum segredo real, e .env está no .gitignore deste pacote.

Falha 4 — Muitos componentes sem tarefa concluída. Sintoma: o board de design tem doze telas, cada uma revisada e aprovada isoladamente, mas nenhum caminho de ponta a ponta jamais foi testado inteiro. Causa: revisão por componente recompensa polimento visual local, não conclusão de tarefa; é possível "terminar" todas as telas sem nunca ter completado a tarefa de triagem uma única vez. Resposta: a fatia deste capítulo tem exatamente quatro telas (fila, detalhe, atribuição, histórico), cada uma mapeada a um passo da mesma tarefa, e o critério de aceite documentado em editorial-spec.md é "a tarefa completa passa", não "as telas existem" — o teste full happy path: triage, assign, then read history é o critério, não uma checklist de componente.

Avaliação: o que os testes provam e o que não provam

examples/deskpilot/ roda 25 testes automatizados no total: 14 em test/domain/ (13 herdados do capítulo 03 sem alteração, mais um novo sobre retry no nível de domínio), 6 em test/api/ (contrato HTTP contra o repositório em memória, sem Docker) e 5 em test/flow/ (o mesmo contrato contra PostgreSQL real, com o papel deskpilot_app). verification.md registra o comando exato e a saída de cada bloco, nesta sessão, em 2026-09-28.

O que isso prova: que a máquina de estados de tickets e sugestões continua correta depois de ganhar uma camada HTTP e um banco; que o isolamento de tenant é redundante em duas camadas independentes, e a camada de banco falha fechado quando mal configurada, não aberto; que retry e duplo clique não duplicam efeito, tanto em memória quanto em Postgres real; que o histórico sobrevive a um restart de container.

O que isso não prova: que um agente de suporte real consegue usar a interface sem ajuda — examples/usability-protocol.md define o roteiro think-aloud e o instrumento de tempo, mas nenhuma sessão com participante real aconteceu para este pacote, e isso está marcado como pendente, não como resultado. Não prova conformidade completa com WCAG 2.2 — a UI aplica três critérios pontuais (2.1.1 Keyboard, 2.1.2 No Keyboard Trap, 4.1.3 Status Messages, este último via a região aria-live em src/web/index.html), o que é diferente de uma reivindicação de conformidade formal, que exige data, nível e lista de páginas por definição do próprio W3C. E não prova que existe demanda real pelo DeskPilot — testar a aplicação e validar demanda são perguntas diferentes, e só a primeira tem evidência neste capítulo.

Custo, segurança e reversibilidade

O custo operacional desta fatia, hoje, é essencialmente zero fora do tempo de engenharia: um container Docker efêmero (--rm, sem volume nomeado, porta de host dinâmica), sem serviço gerenciado, sem chamada de API paga — porque não há chamada de IA em nenhum caminho deste MVP. Isso é deliberado: a baseline determinística precisa ser barata de rodar repetidamente, porque ela vai ser recriada a cada sessão de teste e comparada contra a versão com IA no capítulo 05.

Do lado de segurança, os limites explícitos deste pacote são: PII minimizada (nenhuma fixture contém dado que se pareceria com informação real de uma pessoa), dev login isolado por flag lida a cada requisição, segredo de banco fora do controle de versão, e duas camadas de isolamento por tenant testadas de forma adversarial. O que não está aqui: consentimento de piloto real, decisão de retenção de dado além de um campo retentionDays no Policy herdado do capítulo 03 (ainda não aplicado por um job de expiração), e qualquer afirmação de conformidade regulatória.

Reversibilidade é alta por construção: o container não tem volume nomeado, então pará-lo apaga todo o estado sem deixar rastro em disco; a migração pode ser reaplicada do zero a qualquer momento contra um container novo; e a dependência de produção única (pg) está fixada em lockfile, então reinstalar em uma máquina limpa reproduz exatamente o mesmo grafo de dependências.

Checklist de saída deste capítulo

• npm install a partir do lockfile, sem copiar node_modules.
• Container series-ai-pe04-pg iniciado com --rm, sem volume nomeado, porta dinâmica.
• npm run migrate e npm run seed rodados contra a conexão de dono (DATABASE_URL), nunca contra DATABASE_APP_URL.
• npm test (domínio + API, offline) e npm run test:rls (Postgres real) verdes.
• Restart do container preserva ticket e histórico de auditoria.
• Retry com o mesmo commandId não duplica atribuição nem evento.
• Tenant B não lê nem lista ticket do tenant A, em teste de aplicação e em teste de RLS real.
• Container parado e removido ao final (docker ps -a --filter name=series-ai-pe04-pg vazio).

Exercícios

Básico. Rode o setup completo em examples/deskpilot/README.md numa máquina limpa: npm install, subir o container, migrar, semear, rodar npm test e npm run test:rls. Critério de aceite: os três comandos de teste terminam com fail 0, e você consegue explicar, sem olhar o código, por que npm test não precisa do container. Solução comentada: se npm run test:rls falhar com erro de conexão, o problema mais comum é .env apontando para uma porta antiga — docker port series-ai-pe04-pg 5432/tcp muda a cada docker run (e, como este capítulo documentou em verification.md, pode mudar até num docker restart); releia a porta antes de rodar os testes.

Intermediário. Adicione um teste em test/api/api.test.ts que confirma que a tela de fila mostra corretamente o estado vazio quando um tenant novo, sem tickets seedados, faz login. Critério de aceite: o teste falha antes de qualquer mudança de código (confirmando que hoje não há tenant fixture vazio para testar isso) e passa depois de você seedar — só para o teste, sem alterar seed/seed.ts — um terceiro tenant sem tickets. Solução comentada: a forma mais simples é instanciar um MemoryRepository direto no teste e nunca chamar nada que insira ticket para esse tenant; listQueue já devolve array vazio para um tenant sem linhas, então o teste está verificando o contrato da API ({tickets: []}, não um erro), não uma lacuna de implementação.

Avançado. O capítulo 05 vai introduzir um papel que só pode escrever Suggestion, nunca ler ou escrever Ticket. Modifique migrations/0001_init.sql para criar esse papel (deskpilot_suggester, por exemplo) com GRANT INSERT apenas em suggestions, e escreva um teste em test/flow/ que confirma que uma tentativa desse papel de ler tickets falha por falta de privilégio SQL (não por RLS) — a chamada deve devolver um erro de permissão do Postgres, não uma lista vazia. Critério de aceite: o teste distingue explicitamente "sem privilégio para a tabela" (GRANT ausente) de "com privilégio mas sem linha visível por RLS" (o caso já coberto pelos testes existentes) — são duas defesas diferentes, e confundi-las nesta preparação para o capítulo 05 seria repetir, em miniatura, a Falha #2 deste capítulo.

Glossário

• Fatia vertical: um caminho completo de ponta a ponta (UI → backend → banco) para uma única tarefa, em vez de uma camada inteira (todas as telas, ou todo o banco) sem as outras.
• Idempotência de comando: propriedade de que aplicar o mesmo comando (identificado por commandId) mais de uma vez produz o mesmo efeito de aplicá-lo uma vez.
• RLS (Row-Level Security): mecanismo do PostgreSQL que restringe quais linhas uma sessão pode ver ou modificar, por política, independentemente do que a checagem de privilégio SQL padrão permitiria.
• Papel não-dono (non-owner role): conexão de banco que não é dona das tabelas que acessa, e por isso está de fato sujeita às políticas de RLS — ao contrário do dono, que as ignora por padrão.

Ponte para o capítulo 05

O capítulo seguinte entra exatamente onde este para: a tabela suggestions e o método getSuggestion já existem no contrato DeskPilotRepository, mas nada neste pacote escreve uma sugestão. O capítulo 05 introduz uma sugestão tipada de categoria e resumo em modo shadow, com adaptador offline e provedor real opcional, dataset rotulado com holdout separado, e a decisão explícita de que prioridade final, atribuição e comunicação externa continuam sendo comandos humanos validados pelo mesmo applyCommand que este capítulo já testou. Nenhuma regra de domínio deste capítulo muda; o que muda é que, pela primeira vez na série, existirá uma saída de modelo para comparar contra esta baseline determinística — e a baseline só é uma baseline honesta porque este capítulo mediu o que ela de fato faz, não o que pareceu fazer num vídeo de quatro minutos.