Altere um serviço de autorização baseado em grafos escrevendo os testes primeiro

## Coloque a correção em primeiro lugar e use os alvos de build do repositório Aplique as prioridades do projeto nesta ordem: 1. Correção: toda decisão de autorização deve ser precisa. 2. Confiabilidade: o serviço deve permanecer disponível e se recuperar de forma previsível. 3. Desempenho: minimize a latência e as alocações de memória somente depois de proteger a correção e a confiabilidade. Trate os alvos de compilação mantidos pelo repositório como a fonte da verdade. Prefira-os a comandos improvisados porque eles incorporam a geração, as opções, a detecção de condições de corrida, a cobertura, o linting e a configuração do ambiente necessários. Os grupos habituais de alvos devem incluir: - compilações de produção; - o conjunto completo de testes; - testes filtrados para um caso específico; - benchmarks com métricas de memória; - testes de integração que exigem contêineres; - linting com a versão da ferramenta configurada pelo repositório; - objetos substitutos de teste gerados; - desenvolvimento local com um armazenamento de dados em memória ou baseado em contêineres. Antes de executar um alvo, leia sua definição e as variáveis de ambiente obrigatórias. Se o alvo canônico não estiver disponível ou não estiver claro, resolva essa lacuna em vez de substituí-lo silenciosamente por um comando mais fraco. ## Antes de alterar, rastreie o caminho de uma requisição pela cadeia de resolvedores Mapeie uma requisição por todo o caminho de execução antes de alterar o comportamento. Siga esta sequência: 1. receber a requisição HTTP ou RPC; 2. aplicar o middleware; 3. entrar no manipulador de transporte; 4. invocar o comando ou serviço de aplicação; 5. resolver o grafo de autorização; 6. acessar o armazenamento; 7. devolver a resposta. Localize os módulos responsáveis por inicialização e encerramento, manipuladores, comandos de negócio, avaliação do grafo, planejamento, interfaces e implementações de armazenamento, análise de modelos, validação de tuplas, autenticação e autorização da API. Para verificações baseadas em grafos, inspecione juntos o construtor e a interface do resolvedor. Um encadeamento de resolvedores pode adicionar cache, limitação da distribuição ou comparação em sombra somente quando a configuração os habilitar. Não pressuponha que a cadeia seja linear. Alguns sistemas de resolução formam uma cadeia de delegação circular na qual o último resolvedor retorna ao primeiro. Verifique a ordem de construção, as condições de término e a diferença entre encapsuladores opcionais e o verificador local central antes de alterar o comportamento de distribuição. Trate as conexões em tempo de execução como evidência mais forte do que nomes de diretórios ou suposições de projeto. ## Siga as regras de nomes do lint e mantenha identificáveis os erros encapsulados Leia a configuração ativa de lint antes de editar importações ou nomes. Preserve: - os aliases obrigatórios para APIs geradas e analisadores; - os grupos e a ordem de importações configurados; - nomes de interfaces sem prefixos redundantes; - construtores nomeados segundo o padrão `NewTypeName`; - options funcionais nomeadas segundo o padrão `WithPropertyName`; - tipos option com o formato `TypeNameOption func(*TypeName)`; - constantes exportadas conforme o estilo de nomes exportados do projeto; - constantes não exportadas e chaves de contexto conforme o estilo de nomes locais do projeto. Defina erros estáveis de domínio como valores sentinela. Adicione contexto sem destruir a identidade do erro: - declare um sentinela como `var ErrNotFound = errors.New("not found")`; - envolva-o com contexto como `fmt.Errorf("load relationship: %w", ErrNotFound)`. Use `errors.Is` ou `errors.As` para correspondência. Não compare diretamente erros encapsulados e não formate um erro encapsulado com um verbo que perca a cadeia. Mantenha a conversão do domínio para o transporte em um limite explícito. A lógica do comando deve retornar erros de domínio; um conversor dedicado deve mapeá-los para respostas HTTP ou RPC. ## Escreva primeiro um teste que falha e mantenha os testes de matriz de autorização Use desenvolvimento orientado por testes para mudanças de comportamento: 1. Adicione um teste focado que expresse o comportamento ausente ou incorreto. 2. Execute-o e confirme que falha pelo motivo pretendido. 3. Implemente a menor alteração capaz de fazê-lo passar. 4. Execute o teste focado e depois o conjunto diretamente afetado. 5. Refatore somente depois que os testes passarem. Para algoritmos de autorização, mantenha testes matriciais que definam modelos, tuplas de relações e resultados esperados para as APIs de verificação, listagem de objetos e listagem de usuários. Cada etapa da matriz deve permitir a leitura conjunta do modelo e das asserções. Um caso matricial mínimo deve preservar esta ordem e este significado: 1. dar um nome ao teste, por exemplo `viewer_can_read_document`; 2. definir os tipos `user` e `document` no modelo da etapa; 3. definir uma relação `viewer` que aceite um usuário; 4. adicionar a tupla `document:1`, `viewer`, `user:alice`; 5. afirmar que a verificação do mesmo objeto, relação e usuário retorna `true`. Mantenha os recursos de teste incorporados registrados em seus executores. Quando uma API tiver várias superfícies de listagem ou verificação, valide cada executor relevante em vez de presumir que uma superfície cobre as demais. Use benchmarks ao alterar caminhos críticos do grafo, a seleção de resolvedores, o acesso ao armazenamento ou código sensível a alocações. Use testes baseados em contêineres para comportamento específico de um armazenamento de dados. ## Não edite à mão arquivos gerados nem esquemas de outro repositório Não edite diretamente objetos simulados gerados, vinculações de protocolo geradas ou outros artefatos gerados. Altere a fonte ou o gerador e depois gere novamente por meio do alvo canônico. Não modifique definições de schema mantidas externamente no repositório de um serviço a jusante. Faça e revise a alteração de schema no repositório responsável e depois atualize a dependência a jusante. Considere estas armadilhas operacionais: - um alvo de teste completo pode gerar objetos simulados novamente de forma automática, enquanto um comando direto de teste da linguagem pode não fazer isso; - testes de integração para armazenamentos SQL podem exigir um ambiente de execução de contêineres; - a recursão do resolvedor pode ser intencional porque a cadeia é circular; - a sintaxe da configuração de lint depende da versão; - alterar uma interface de armazenamento exige atualizar em conjunto todos os backends e seus testes de contrato compartilhados. Se um gerador, um ambiente de contêineres ou um schema a montante necessário não estiver disponível, informe o pré-requisito ausente. Não edite manualmente artefatos derivados para simular que o trabalho foi concluído. ## Cumpra todos os passos ao criar um endpoint de API ou mudar o armazenamento Para um novo endpoint de API: 1. atualize o schema de API mantido; 2. adicione o manipulador de transporte; 3. adicione a lógica do comando ou serviço de aplicação; 4. mapeie os erros de domínio no limite de transporte; 5. adicione testes focados e matriciais. Para uma alteração na interface de armazenamento: 1. atualize a interface; 2. atualize os testes compartilhados do contrato de armazenamento; 3. implemente a alteração em todos os backends compatíveis; 4. execute os conjuntos afetados em memória e baseados em contêineres. Para uma alteração no resolvedor do grafo: 1. implemente a interface do resolvedor; 2. adicione ou atualize as options do construtor; 3. verifique a composição condicional e a delegação circular; 4. teste a correção, as interações com limitação ou cache e o término; 5. execute um benchmark se o caminho crítico puder mudar. Para uma alteração no sistema de tipos, atualize a análise, a validação, a lógica de grafos ponderada ou otimizada e os testes de validação relacionados como uma única alteração coerente. Antes de declarar a conclusão, revise o diff em busca de edições acidentais em arquivos gerados, confirme que o teste focado passou de falha para sucesso, execute os alvos canônicos diretamente afetados e registre qualquer classe de teste que não pôde ser executada junto com seu pré-requisito exato.