Especifica estágios de processamento, armazenamento, metadados, interfaces, versionamento e dependências para transformação de consulta. Esta referência fixa o limite de adoção, comportamento em caso de falha e evidências observáveis, deixando os limites específicos do ambiente configuráveis.
Status do pacote: contexto de referência pronto para revisão humana. O contrato e os cenários de teste estão completos, mas não se afirma que uma implementação adotante os tenha aprovado.
Decisão
Para transformação de consulta, adote uma linhagem versionada de origem, transformação, índice e controle de acesso. Use um limite próprio, modelo de estado explícito e interfaces versionadas; mantenha decisões de política separadas de adaptadores e efeitos colaterais. Este pacote é um contrato de referência: a equipe adotante deve escolher limites numéricos, provedores, jurisdições e responsáveis operacionais a partir de evidências em seu próprio ambiente.
Escopo
- Os atores, entradas, saídas, estados, versões de política ou esquema e resultados visíveis externamente da transformação de consulta descritos por este bloco arquitetural.
- Interfaces primárias e alternativas, trabalhos em segundo plano, caches, integrações, caminhos de suporte e evidências que podem exercer o mesmo limite.
- Configuração específica de adoção, implantação, recuperação e responsabilidades de verificação necessárias para aplicar a referência com segurança.
Fora deste bloco
- Escolher um fornecedor universal, framework, jurisdição, limite numérico, período de retenção ou objetivo de nível de serviço para todos os adotantes.
- Afirmar que cenários empacotados foram executados contra uma implementação downstream ou que esta referência concede certificação legal, de segurança ou acessibilidade.
Contrato
- Preservar identificador de origem, versão, localização, escopo de acesso, parser, normalização, chunk, embedding e versões de índice para cada unidade recuperável.
- Aplicar filtros de acesso antes que resultados, trechos, contagens, caches e contexto do modelo sejam expostos; filtragem posterior sozinha não é suficiente.
- Isolar falhas de parsing ou transformação e impedir que um artefato parcial substitua silenciosamente a última versão completa.
- Avaliar comportamento de recuperação e resposta fundamentada em casos representativos versionados, incluindo conflitos, ausência, desatualização e texto adversarial.
- Documentar propriedade dos componentes e direção permitida de dependência, incluindo quais dados podem atravessar cada limite.
- Fazer com que caminhos síncronos, assíncronos e em lote implementem as mesmas invariantes de autoridade e estado.
- Definir um mapeamento tipado e versionado para campos, operadores, valores, nulos, intervalos, datas, fusos horários, ordenação, paginação e construções não suportadas entre modelos de consulta fonte e alvo.
- Validar antes da execução, preservar restrições de autorização, emitir uma forma canônica explicável e rejeitar transformações ambíguas ou com perda em vez de ampliar a consulta silenciosamente.
Orientações para implementação
- Comece com o estado do domínio e contrato de interface, depois conecte adaptadores, armazenamento, filas e código específico do provedor.
- Modele entradas, saídas, atores, estados, invariantes, efeitos colaterais e evidências da transformação de consulta antes de selecionar detalhes de framework ou fornecedor.
- Armazene a versão aplicável do contrato ou política de transformação de consulta com o estado material para que migrações, reprodução e decisões de suporte permaneçam atribuíveis.
- Introduza o caminho por trás da implantação controlada, compare resultados esperados e observados, e mantenha uma rota de recuperação testada até que a evidência de adoção esteja completa.
Tratamento de falhas e salvaguardas
- Se a proveniência, escopo de acesso ou conteúdo requerido estiver faltando, exclua a unidade e exponha uma lacuna de cobertura diagnosticável em vez de fabricar completude.
- Estado inválido ou contraditório da transformação de consulta é rejeitado ou isolado; a implementação nunca supõe um valor que amplie autoridade ou duplique um efeito.
- Retentativas são limitadas e usam identidade durável; após esgotamento, o trabalho alcança um estado terminal inspecionável com um responsável contabilizável.
Verificação e operações
- Exercite o contrato através de cada adaptador e prove que uma dependência falha não pode contornar o limite autoritativo.
- Monitore sucesso, negação, falha de validação, falha de dependência, esgotamento de retentativas e recuperação da transformação de consulta por versão do contrato sem dimensões sensíveis do payload.
- Reexecute fixtures positivos e negativos pareados após mudanças de política, esquema, dependência, migração ou limite e preserve as evidências resultantes.
Premissas de adoção
- Nomes e valores no exemplo são um fixture concreto, não padrões universais; adotantes os substituem por meio de evidências documentadas e propriedade.
- O sistema adotante pode fornecer identidade autenticada, versões duráveis de operação ou registro, telemetria limitada e um caminho controlado para mudanças.
Os exemplos com aparência executável neste pacote são fixtures e contratos de aceitação. Execute o validador da coleção para verificar estrutura e metadados, depois traduza e execute os cenários no repositório alvo antes de registrar evidências de implementação.
Referências
- NIST AI 600-1, Generative AI Profile (aplica-se a partir de 2026-09-08)