[TASK] Contrato: validar fingerprint e probe autoritativo da API

[elson-vinicius-lopes]

PBI pai

#178

Entrega esperada na LayoutParserApi

• fingerprint versionado por layout e cache invalidado por hash/versão;
• relatório de colisões no refresh do catálogo;
• probe estrito sem aprendizado, transformação ou persistência;
• POST /api/parse/auto (ou contrato aceito equivalente) com unique, ambiguous e not_found;
• layout resolvido internamente por layoutGuid, sem XML descriptografado no navegador;
• códigos de evidência/conflito sanitizados e correlationId preservado.

Gates duros mínimos

Formato físico, largura explícita, marcadores/segmentos, ordem/hierarquia, cardinalidade validada e discriminadores cadastrados. Nome/extensão/score não autorizam seleção.

Critérios de aceite

• Parse atual não é reutilizado como booleano de match: success=true tolera linhas desconhecidas.
• Metadados legados de MinimalOccurrence são migrados ou excluídos da prova dura.
• Colisões MQSeries Marelli/Comau permanecem ambíguas sem discriminador explícito.
• Testes cobrem concorrência, timeout, limites e ausência de efeitos colaterais.

Bloqueio

Dependência externa ao LayoutParserReact; deve ser espelhada/implementada no backlog da API.

Aceite adicional do contrato Top 5

@lp-contract-qa deve validar que o contrato da API:

• entrega até cinco rankedCandidates nos resultados não únicos, com total e indicador de truncamento;
• separa candidato compatível de mera sugestão aproximada;
• fornece ranking explicável e determinístico, incluindo empates, evidências, conflitos e limitações;
• não popula selectedLayout nem inicia parse em ambiguous/not_found;
• aceita escolha explícita por layoutGuid e devolve identificador de auditoria;
• preserva status original, origem da escolha, rank/score apresentado, versões do algoritmo/catálogo e correlationId na proveniência;
• não registra payload documental nem identidade legível desnecessária.

[elson-vinicius-lopes]

Dependência espelhada no backlog da API: LayoutParser/LayoutParserApi#213. Este item permanece bloqueado até o contrato autoritativo ser entregue e aceito pelo front.

[elson-vinicius-lopes]

Espelho da dependência: LayoutParser/LayoutParserApi#213. O discovery de fingerprint e colisões está em LayoutParser/LayoutParserApi#214. Este item do front passa a representar validação/aceite do contrato por @lp-contract-qa; a implementação permanece exclusivamente na API.

[elson-vinicius-lopes]

Contrato validado e consumido entre API #222 e front #186. O front falha fechado se unique vier sem selectedLayout e não recebe XML descriptografado.