SLA por calendário: o bug que abriu o capítulo, resolvido

Voltando ao ticket reaberto na segunda-feira. O Policy de cada tenant declara um Calendar explícito — não uma suposição sobre fuso ou feriado:

export interface Calendar {
  businessStartMinuteUtc: number;
  businessMinutesPerDay: Record<number, number>;
  holidaysIso: string[];
}

A versão errada — a que abriu este capítulo — está em domain.ts, exportada de propósito para que o teste possa comparar as duas e provar a diferença, nunca para ser chamada em código de produção:

export function naiveReopenDueAt(reopenedAtIso: string, priority: Priority, policy: Policy): string {
  return addBusinessMinutes(reopenedAtIso, policy.slaMinutesByPriority[priority], policy.calendar);
}

A versão correta calcula quanto do orçamento de SLA já foi consumido em minutos úteis entre a criação e a primeira resolução, e concede só o restante, com um piso mínimo configurável (reopenFloorMinutes) para o caso em que o orçamento já esteja praticamente esgotado:

export function computeReopenDueAt(params: {
  createdAtIso: string;
  resolvedAtIso: string;
  reopenedAtIso: string;
  priority: Priority;
  policy: Policy;
}): string {
  const totalBudget = params.policy.slaMinutesByPriority[params.priority];
  const consumed = businessMinutesElapsed(params.createdAtIso, params.resolvedAtIso, params.policy.calendar);
  const remaining = Math.max(totalBudget - consumed, params.policy.reopenFloorMinutes);
  return addBusinessMinutes(params.reopenedAtIso, remaining, params.policy.calendar);
}

O teste naive reopen grants more time than the calendar-aware reopen after heavy SLA consumption fixa um cenário sintético — ticket criado numa segunda, resolvido na segunda seguinte, reaberto no mesmo instante — em que o orçamento normal (960 minutos) já foi majoritariamente consumido. Ele confirma que naiveReopenDueAt devolve uma data mais tardia (mais generosa) do que computeReopenDueAt, exatamente o padrão do bug de abertura: o recálculo do zero esconde quanto tempo já foi gasto. Um segundo teste, computeDueAt skips the weekend for a Friday-afternoon urgent ticket, fixa um ticket urgente criado numa sexta às 19h30 UTC, trinta minutos antes do fim do expediente: como o orçamento de duas horas não cabe no que resta do dia, o prazo precisa cair na segunda seguinte — nunca dentro do fim de semana, mesmo que a soma ingênua de "duas horas corridas" caísse tranquilamente ainda na sexta à noite.

Vale registrar o limite honesto deste modelo: businessMinutesElapsed soma dias inteiros de orçamento entre criação e resolução, uma aproximação suficiente para provar o contraste entre cálculo ingênuo e correto, não uma medição de precisão de minuto para produção — isso está documentado em examples/rules.md, Limites explícitos.

Bounded contexts sem microservices

O prompt deste capítulo cita Martin Fowler sobre bounded context (2014-01-15, acesso 2026-09-28): um bounded context é separação lógica de modelo, e o próprio artigo dá como exemplo válido "múltiplos contextos dentro da mesma aplicação". O DeskPilot v1 usa exatamente essa leitura. Dentro do mesmo processo e do mesmo banco, três vocabulários vivem separados:

• Triagem — Ticket, Suggestion, Assignment. Vocabulário: estado, prioridade, SLA, dono.
• Identidade — Tenant, User, papel, status. Vocabulário: autenticação, autorização, isolamento.
• Faturamento — fora do escopo de código deste capítulo, mas já citado como fonte da Oportunidade A (ambiguidade cobrança vs. produto). Vocabulário: plano, cobrança, limite contratual — que não deve ser confundido com "tipo de problema do ticket" só porque os dois aparecem na mesma tela para o agente.

A confusão entre "cobrança" como assunto de ticket e "cobrança" como sistema de billing é, na prática, a origem da Oportunidade A. Modelar bounded contexts aqui não significa três bancos de dados ou três deploys — significa que o tipo Ticket não importa conceitos de faturamento, e que uma Suggestion de categoria "cobrança" é uma etiqueta de triagem, não uma consulta ao sistema de billing. Errar esse limite é como misturar dois idiomas na mesma frase e esperar que o leitor entenda qual palavra pertence a qual gramática.

Contrato de eventos: identificadores, não conteúdo

Todo AuditEvent carrega event_id, tenant_id, ticket_id, actor_id, occurred_at, schema_version e correlation_id. O schema em examples/events.schema.json fecha a porta com "additionalProperties": false — adicionar um campo de texto livre exige uma mudança de schema revisada, nunca um vazamento silencioso:

{
  "required": [
    "event_id", "tenant_id", "ticket_id", "actor_id",
    "occurred_at", "schema_version", "correlation_id", "type"
  ],
  "additionalProperties": false
}

Os testes em events.test.ts confirmam isso nos dois sentidos: um evento bem formado passa, e um evento com um campo ticket_text ou ai_summary é rejeitado por unexpected_property. Essa é a defesa contra a quarta falha obrigatória deste capítulo, discutida adiante: telemetria de produto não é o lugar para reconstruir o que o cliente escreveu.

As quatro falhas obrigatórias

Falha 1 — prompt usado como autorização

Sintoma: um comando chega ao backend acompanhado de texto como "o modelo confirmou que este ticket deve ser resolvido"; alguém decide que essa frase, vinda de uma resposta de IA, é suficiente para executar RESOLVE.

Causa: confundir a saída de um modelo de linguagem — que é texto, sujeito a injeção e a erro de interpretação — com uma autorização, que precisa vir de um ator autenticado com papel verificável.

Resposta: applyCommand nunca lê o conteúdo de um prompt ou de um ticket para decidir permissão. A checagem de papel usa actor.role, um campo estruturado que vem da sessão autenticada, nunca do texto. O teste ai role can never carry a state-changing command, even claiming manager-shaped text simula exatamente esse ataque: um ator com role: "ai" tenta RESOLVE, e a função rejeita com ai_role_cannot_command antes mesmo de olhar a tabela de transições. Isso mapeia diretamente para LLM01:2025 Prompt Injection no OWASP Top 10 for LLM Applications (edição 2025, acesso 2026-09-28): a taxonomia nomeia a classe de ataque, mas a defesa real é este teste, não uma lista de verificação.

Falha 2 — SLA sem calendário

Sintoma: o ticket reaberto na segunda-feira que abriu este capítulo. Um prazo recalculado "do zero" parece mais seguro (mais tempo!), mas quebra a promessa original do SLA e some com a informação de quanto tempo já foi gasto.

Causa: somar horas corridas, ou reiniciar o orçamento de SLA a cada evento, em vez de consultar um calendário de negócio declarado e subtrair o que já foi consumido.

Resposta: computeReopenDueAt e businessMinutesElapsed, testados contra naiveReopenDueAt no mesmo cenário sintético. Nenhuma legislação ou obrigação contratual real foi deduzida aqui — o calendário é um dado de configuração por tenant (Policy.calendar), a confirmar com o cliente real antes de qualquer piloto, exatamente como pede a restrição deste pacote.

Falha 3 — IA alterando estado final

Sintoma: o botão "aceitar sugestão" da interface, sozinho, já move o ticket para assigned ou resolved, sem uma segunda confirmação de comando vinda do agente.

Causa: tratar a conveniência de "um clique" como equivalente a "uma decisão autorizada", fundindo o ciclo de vida da sugestão com o ciclo de vida do ticket.

Resposta: applySuggestionCommand devolve só um Suggestion atualizado; nunca um Ticket. O teste suggestion acceptance does not touch ticket state verifica isso explicitamente, checando que a chave "ticket" nem existe no retorno. Essa separação também é a resposta prática a LLM06:2025 Excessive Agency: a IA nunca tem, estruturalmente, agência para fechar seu próprio ciclo de sugestão em uma ação real.

Falha 4 — evento analítico contendo PII

Sintoma: um evento de telemetria carrega "resumo: cliente pediu reembolso do cartão final 1234" para "facilitar dashboards depois".

Causa: tratar o log de auditoria como um lugar conveniente para guardar contexto de negócio, sem perceber que esse mesmo log alimenta análises, exportações e, eventualmente, terceiros.

Resposta: o schema fechado em events.schema.json, testado por an event carrying ticket text is rejected e an event carrying an AI-generated summary is rejected. A defesa não é uma política de redação escrita depois — é a ausência estrutural de qualquer campo de texto livre no tipo AuditEvent.

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

Os testes provam que, dado um ator e um ticket com os campos descritos, a função de transição obedece isolamento de tenant, papel, status, concorrência otimista e a tabela de estados — e que o contrato de evento rejeita conteúdo fora da lista fechada de campos. Eles não provam que a UI do DeskPilot impede um agente mal-intencionado de forjar uma sessão, que o provedor de IA real nunca vai gerar uma sugestão tendenciosa, ou que o calendário de negócio configurado está correto para um cliente real. A citação da documentação do PostgreSQL sobre row security policies (acesso 2026-09-28) é relevante aqui por um motivo específico: "table owners normally bypass row security as well" — ou seja, se este isolamento fosse implementado só como uma política de RLS no banco, rodando com o papel dono da tabela, ele não protegeria nada. O teste de isolamento deste capítulo roda inteiramente em código de aplicação; uma política de RLS complementar, se adotada depois, precisaria ser testada com um papel de aplicação sem BYPASSRLS e sem ownership — não como proteção única.

Custo, segurança e reversibilidade

Custo: formalizar sete tipos, duas máquinas de estado e um schema de evento antes de qualquer tela é trabalho que não aparece em uma demonstração rápida. O retorno vem depois: cada regra nova (uma quinta prioridade, um novo papel) é uma linha na tabela de decisão e um teste, não uma investigação arqueológica em condicionais espalhadas.

Segurança: o risco central deste capítulo não é "a IA vai inventar uma resposta errada" — é "alguém vai tratar a resposta da IA como comando". A defesa é estrutural (papel ai fora de toda tabela de permissão), não comportamental (pedir educadamente ao modelo para não fazer isso).

Reversibilidade: reabrir um ticket não apaga o evento de resolução anterior; ele soma um novo evento, com reopenCount incrementado. O teste reopen preserves ticket identity and increments reopenCount without deleting history verifica isso na projeção do ticket; num backend real, o AuditEvent de resolução original continuaria como linha própria e imutável no log — a reversibilidade vem de nunca sobrescrever histórico, só adicionar a ele.

Checklist antes de conectar uma IA a qualquer fluxo de decisão

• Toda transição de estado tem uma linha explícita numa tabela de decisão, com papéis permitidos.
• Nenhum papel de IA aparece em nenhuma tabela de transição de estado que afete o mundo real.
• SLA e prazo usam um calendário de negócio declarado, nunca soma de horas corridas nem suposição de fuso.
• Aceitar uma sugestão de IA e executar uma ação real são duas chamadas distintas, com dois autores distintos no log.
• O contrato de evento tem lista fechada de campos; texto de ticket ou resumo gerado por IA nunca entra por padrão.
• Isolamento por tenant é verificado no código de aplicação antes de qualquer política de banco ser tratada como suficiente.
• Todo teste adversarial (tenant cruzado, papel sem permissão, transição inválida, evento com PII) roda e falha do jeito esperado, não só os caminhos felizes.

Exercícios

Básico. Adicione a prioridade "critical" ao tipo Priority e a Policy.slaMinutesByPriority, com um orçamento menor que "urgent". Critério de aceite: um novo teste cria um ticket "critical" e confirma que computeDueAt devolve um prazo mais curto que o de um ticket "urgent" criado no mesmo instante. Solução comentada: basta estender o Record<Priority, number> no objeto POLICY de teste e o tipo Priority em domain.ts; nenhuma outra função muda, porque toda a lógica de cálculo já é paramétrica em priority.

Intermediário. Adicione uma transição triaged → new chamada RETRIAGE, permitida só para manager, usada quando uma triagem inicial se mostra errada antes de qualquer atribuição. Critério de aceite: um teste feliz confirma a transição para manager; um teste adversarial confirma que agent recebe actor_not_permitted:agent. Solução comentada: adicione uma entrada em TICKET_TRANSITIONS.triaged.RETRIAGE com allowedRoles: ["manager"]; nenhuma mudança é necessária em applyCommand, porque a função já lê a tabela genericamente — essa é a vantagem de centralizar as regras numa estrutura de dados em vez de num switch crescente.

Avançado. Implemente businessMinutesElapsed com granularidade de minuto (em vez de dia inteiro) para o dia de resolução, e escreva um teste que mostre um caso em que a versão atual (dia inteiro) e a versão nova discordam em mais de 60 minutos de orçamento de SLA restante. Critério de aceite: o teste falha contra a implementação atual e passa contra a nova, documentando a diferença numericamente, não só qualitativamente. Fora do escopo deste capítulo, fica registrado como pendência honesta em examples/rules.md.

Glossário

• Máquina de estados: conjunto fechado de estados e transições permitidas entre eles, onde cada transição é uma decisão explícita, não um efeito colateral.
• Tabela de decisão: estrutura de dados (não código imperativo) que mapeia combinações de estado, comando e papel para uma decisão de permitir ou negar.
• Concorrência otimista: técnica que usa um campo de versão (version) para detectar se dois comandos tentaram mudar o mesmo registro ao mesmo tempo, rejeitando o que chegou com uma versão desatualizada.
• Bounded context: fronteira de vocabulário dentro de um domínio, onde o mesmo termo ("cobrança") pode significar coisas diferentes fora dela sem gerar contradição.
• Evento de auditoria (AuditEvent): registro imutável e append-only de uma transição aceita, usado para reconstrução de histórico e telemetria, sem conteúdo de negócio sensível.

Ponte para o capítulo 04

O capítulo 04 (../product-designer-serie-04/) recebe este domínio como entrada e constrói a primeira fatia vertical completa: importar ticket, revisar, atribuir e auditar, com dois tenants fixture, login de desenvolvimento isolado de produção e uma UI web simples sobre TypeScript, Node.js e PostgreSQL — stack didática, com versões e lockfile a fixar na sessão de implementação, não um endosso deste repositório. Nenhum benefício real do DeskPilot foi comprovado até aqui; o que este capítulo entrega é a garantia de que, quando a IA entrar em cena no capítulo seguinte, ela vai encontrar um contrato que já sabe dizer não.