Rails e Proveniência
As respostas clínicas do Clinical Corvus usam rails versionados para tornar evidência, contexto de paciente e rota de execução auditáveis. O contrato atual é emitido pelo backend e resolvido no frontend por um adapter único.
Objetos canônicos
| Objeto | Responsabilidade | Campos principais |
|---|---|---|
ClinicalEvidencePacket | Evidência usada ou rejeitada para uma resposta. | packet_hash, query_frame, evidence_outcome, ledger_summary, items, provider_plan, provider_trace, exclusion_counts, gate_snapshot |
PatientContextManifest | Contexto de paciente disponível para a resposta. | manifest_hash, patient_context_status, patient_refs, included_sections, omitted_sections, freshness, phi_egress_state, case_state_ref, open_decisions |
CorvusProvenance | Registro da rota, gates e versão da resposta. | provenance_hash, provenance_status, packet_hash, manifest_hash, route, agent_type, finalizer_route_context, gate_precedence_applied, gate_snapshot, verifier_snapshot, feature_flag_snapshot |
Esses nomes e campos vêm dos modelos backend atuais. A UI não deve inventar nomes alternativos como evidence_ledger dentro do packet, included_domains dentro do manifest, ou path_selection dentro da provenance quando o backend não emite esses campos nesse objeto.
Estado da resposta
final_answer_state é estado de answerability, não um campo nativo de CorvusProvenance. O frontend o extrai de answerability_assessment, result.final_answer_state ou payload.final_answer_state, e então normaliza:
| Backend | UI |
|---|---|
clinical_answer_ready | ready |
partial_but_useful | partial |
safe_insufficiency | insufficient_evidence |
wrong_domain_blocked | blocked |
safety_blocked | blocked |
needs_clinician_review | review |
Estados adicionais de qualidade clínica podem aparecer em telemetry, como safe_partial_with_actionable_guidance, partial_but_unsupported e unsafe_or_misleading_partial. Eles devem ser tratados como sinais de revisão, não como autorização de uso automático.
Finalizer
O finalizer anexa os rails de forma idempotente depois das decisões de safety, PHI e evidence gates. Ele preserva early returns e short-circuits: uma resposta bloqueada ou insuficiente ainda deve carregar o máximo possível de provenance para auditoria.
Frontend
agentResponseResolvers.ts é o ponto único de propagação para esses objetos. Superfícies como CorvusHub, ResearchQualityPanel, ChatMessage e cards de resposta devem consumir esse resolver em vez de parsear payloads ad hoc.
Superfícies não canônicas
Nem toda ação de IA passa pelo mesmo finalizer. Academy research, helper actions, análise laboratorial e partes do clipboard/plan pipeline podem expor provenance limitada. A UI deve rotular essa condição em vez de apresentar a saída como resposta clínica canônica.
Regra de documentação
Sempre documente os rails com os nomes reais do backend:
ClinicalEvidencePacket.packet_hash,ledger_summary,items,provider_tracePatientContextManifest.included_sections,omitted_sections,phi_egress_stateCorvusProvenance.route,packet_hash,manifest_hash,gate_snapshot
Evite claims públicas de "fully validated" ou "clinical-grade" baseadas apenas na presença desses objetos.