evo360-types 1.3.552 → 1.3.555

package/dist/types/evo-csq/index.ts

@@ -0,0 +1,888 @@
+// Tipos do CSQ 2.0 (Conversation Sales Quality) — feat-154.
+// Schemas zod correspondentes ficam em src/apps/evo-csq/zod-schemas.ts;
+// estes tipos sao escritos a mao e mantidos em paralelo (convencao do projeto:
+// `apps/` = zod, `types/` = interfaces TS).
+//
+// Contrato de nomes/codigos: hub-medica-docs/features/feat-154-csq-2-0/report-spec.md
+// (§2 estrutura, §3 indicadores, §4 rubrica, §5 claims, §6 alertas) e o
+// "Adendo pos-parecer" do plan.md (§A–§I), que prevalece sobre o corpo do plano.
+
+import { IFireDoc } from "../shared";
+
+export * from "./fb_collections";
+
+// ───────── Versao da rubrica ─────────
+
+/** Versao da rubrica da plataforma gravada em cada avaliacao. Pesos e criterios
+ *  sao da plataforma (nao do tenant); mudar pesos exige nova versao. */
+export const CSQ_RUBRIC_VERSION = "v1";
+
+// ───────── Enums / Literals ─────────
+
+/** Modo do CSQ por departamento (gravado no binding da HubIA).
+ *  - `off`    : nao avalia (default quando ausente).
+ *  - `shadow` : avalia e grava o laudo, sem notificar supervisores.
+ *  - `active` : avalia, grava e notifica quando ha alerta critico novo. */
+export type CsqMode = "off" | "shadow" | "active";
+
+/** Status derivado do score (faixas do CSQ 1.0): >=90 Excelente, 80-89 Bom,
+ *  65-79 Regular, 50-64 Ruim, <50 Critico. `pending_judge` = laudo F0 gravado
+ *  sem julgamento do LLM (fase 0 ou falha do juiz). */
+export type CsqStatus =
+  | "Excelente"
+  | "Bom"
+  | "Regular"
+  | "Ruim"
+  | "Crítico"
+  | "pending_judge";
+
+/** Severidade do alerta. `critica` dispara notificacao no modo `active`. */
+export type CsqSeverity = "critica" | "alta" | "media" | "baixa";
+
+/** Origem do alerta: `deterministic` = so codigo; `llm` = so juiz;
+ *  `hybrid` = claim do juiz verificado por codigo (report-spec §5). */
+export type CsqAlertSource = "deterministic" | "llm" | "hybrid";
+
+/** Escopo do alerta: `ticket` = neste atendimento; `journey` = na jornada. */
+export type CsqAlertScope = "ticket" | "journey";
+
+/** Ciclo de vida do alerta. Um alerta da jornada fica `open` no laudo corrente
+ *  ate uma avaliacao posterior constatar a correcao; entao vira `resolved`. */
+export type CsqAlertLifecycle = "open" | "resolved";
+
+/** Estado da rechecagem agendada de agenda (adendo §B). Alertas de agenda
+ *  nascem `pending` (sem auto-fail nem notificacao) e sao reavaliados em
+ *  `closed_at + CSQ_DEFAULTS.recheck_delay_min`.
+ *  - `confirmed_ok`  : a agenda passou a bater — alerta resolvido.
+ *  - `confirmed`     : a divergencia persiste — alerta confirmado.
+ *  - `inconclusive`  : nao foi possivel reler a agenda. */
+export type CsqVerificationState =
+  | "pending"
+  | "confirmed_ok"
+  | "confirmed"
+  | "inconclusive";
+
+/** Status do ledger de execucao (`runs/{eventId}`).
+ *  `quarantined` = payload invalido (zod), ACK sem retry. */
+export type CsqRunStatus = "running" | "done" | "failed" | "quarantined";
+
+/** Escala por criterio: 0 / 50 / 100 / N/A. `NA` sai do denominador. */
+export type CsqCriterionScore = 0 | 50 | 100 | "NA";
+
+/** Veredito humano sobre o laudo (adendo §D / Q9=A). */
+export type CsqReviewVerdict = "agree" | "disagree";
+
+/** Fase do pipeline: `f0` = so indicadores + alertas deterministicos;
+ *  `f1` = com o juiz LLM. */
+export type CsqPhase = "f0" | "f1";
+
+/** Autor de uma mensagem da transcricao entregue ao juiz. */
+export type CsqAuthorKind =
+  | "lead"
+  | "human"
+  | "automation"
+  | "hubia"
+  | "event"
+  | "note";
+
+// ───────── Catalogo de alertas (report-spec §6) ─────────
+
+/** Codigos de alerta v1. Os subtipos de `POLITICA_VIOLADA` e
+ *  `FLUXO_VENDA_NAO_SEGUIDO` vivem em `ICsqAlert.subtype`, nao como codigos. */
+export const CSQ_ALERT_CODES = [
+  "AGENDAMENTO_INFORMADO_NAO_REGISTRADO",
+  "AGENDAMENTO_DIVERGENTE",
+  "AGENDAMENTO_SOBREPOSTO",
+  "CONTRADICAO_PREMISSA_ANTERIOR",
+  "ORIENTACAO_CLINICA_INDEVIDA",
+  "POLITICA_VIOLADA",
+  "ULTIMA_MENSAGEM_SEM_RESPOSTA",
+  "PERGUNTA_NAO_RESPONDIDA",
+  "PROMESSA_NAO_CUMPRIDA",
+  "IDENTIDADE_ERRADA",
+  "DADO_JA_INFORMADO_RECOLETADO",
+  "DADO_OBRIGATORIO_NAO_COLETADO",
+  "FLUXO_VENDA_NAO_SEGUIDO",
+  "MOTIVO_ENCERRAMENTO_INCOMPATIVEL",
+  "SLA_RESPOSTA_ALTO",
+  "LEAD_QUENTE_SEM_FOLLOWUP",
+  "LEAD_ORIGEM_INCONSISTENTE",
+  "LEAD_QUALIFICACAO_INCONSISTENTE",
+  "AUTOMACAO_CONFLITANTE",
+  "DADO_SENSIVEL_SOLICITADO",
+  "URGENCIA_NAO_ENCAMINHADA",
+  "NF_NAO_ENVIADA",
+  "COBRANCA_NAO_ENVIADA",
+] as const;
+
+export type CsqAlertCode = (typeof CSQ_ALERT_CODES)[number];
+
+/** Subtipos de `POLITICA_VIOLADA` (report-spec §6). */
+export const CSQ_POLICY_VIOLATION_SUBTYPES = [
+  "valor",
+  "parcelamento",
+  "convenio",
+  "dia_horario",
+  "procedimento",
+  "modalidade",
+] as const;
+
+export type CsqPolicyViolationSubtype =
+  (typeof CSQ_POLICY_VIOLATION_SUBTYPES)[number];
+
+/** Subtipos de `FLUXO_VENDA_NAO_SEGUIDO` (report-spec §6). */
+export const CSQ_SALES_FLOW_SUBTYPES = [
+  "objecao_sem_argumento",
+  "sem_oferta_concreta",
+  "preco_antes_da_queixa",
+] as const;
+
+export type CsqSalesFlowSubtype = (typeof CSQ_SALES_FLOW_SUBTYPES)[number];
+
+/** Uniao de todos os subtipos aceitos em `ICsqAlert.subtype`. */
+export type CsqAlertSubtype = CsqPolicyViolationSubtype | CsqSalesFlowSubtype;
+
+/** Alertas que forcam auto-fail (`status='Crítico'`, `score <= 49`,
+ *  `escalate=true`). Para `POLITICA_VIOLADA` o auto-fail so vale nos subtipos
+ *  de `CSQ_AUTO_FAIL_POLICY_SUBTYPES`; alertas de agenda so contam depois da
+ *  rechecagem (`verification='confirmed'`, adendo §B). */
+export const CSQ_AUTO_FAIL_ALERT_CODES = [
+  "AGENDAMENTO_INFORMADO_NAO_REGISTRADO",
+  "AGENDAMENTO_DIVERGENTE",
+  "CONTRADICAO_PREMISSA_ANTERIOR",
+  "ORIENTACAO_CLINICA_INDEVIDA",
+  "POLITICA_VIOLADA",
+  "ULTIMA_MENSAGEM_SEM_RESPOSTA",
+  "DADO_SENSIVEL_SOLICITADO",
+  "URGENCIA_NAO_ENCAMINHADA",
+] as const;
+
+export type CsqAutoFailAlertCode = (typeof CSQ_AUTO_FAIL_ALERT_CODES)[number];
+
+/** Subtipos de `POLITICA_VIOLADA` que caracterizam auto-fail (report-spec §4,
+ *  auto-fail 4: valor/parcelamento/convenio contra a politica do roteiro). */
+export const CSQ_AUTO_FAIL_POLICY_SUBTYPES = [
+  "valor",
+  "parcelamento",
+  "convenio",
+] as const;
+
+// ───────── Rubrica v1 (report-spec §4) ─────────
+
+/** Codigo estavel de pilar. */
+export type CsqPillarCode =
+  | "coerencia_historico"
+  | "roteiro_conversao"
+  | "acuracidade"
+  | "responsividade"
+  | "cordialidade_linguagem";
+
+/** Criterio da rubrica: codigo estavel + texto (o que o juiz verifica). */
+export interface ICsqRubricCriterion {
+  code: string;
+  name: string;
+}
+
+/** Pilar da rubrica: codigo estavel, nome e peso (soma = 100). */
+export interface ICsqRubricPillar {
+  code: CsqPillarCode;
+  name: string;
+  weight: number;
+  criteria: ICsqRubricCriterion[];
+}
+
+/** Rubrica da plataforma v1. Pesos: 20/25/25/15/15 (report-spec §4).
+ *  Os `code` sao contrato: aparecem em `ICsqCriterionScore.criterion` e no
+ *  schema da tool de saida do juiz. */
+export const CSQ_RUBRIC_V1: ICsqRubricPillar[] = [
+  {
+    code: "coerencia_historico",
+    name: "Coerência com o histórico do lead",
+    weight: 20,
+    criteria: [
+      { code: "nao_contradiz_premissa", name: "Não contradiz premissa declarada (Estado do lead anterior + conversa)" },
+      { code: "nao_repergunta_dado_informado", name: "Não re-pergunta dado já informado" },
+      { code: "reconhece_contexto", name: "Reconhece o contexto (já é paciente, restrições)" },
+      { code: "nomes_corretos", name: "Trata lead e paciente pelos nomes certos" },
+    ],
+  },
+  {
+    code: "roteiro_conversao",
+    name: "Aderência ao roteiro & fluxo comercial",
+    weight: 25,
+    criteria: [
+      { code: "segue_fluxo_previsto", name: "Segue o fluxo previsto em binding.behavior" },
+      { code: "objecao_tratada_com_argumento", name: "Objeção tratada com o argumento do roteiro" },
+      { code: "dados_obrigatorios_coletados", name: "Dados obrigatórios (capture-data) coletados" },
+      { code: "motivo_fechamento_coerente", name: "Motivo de fechamento coerente com o desfecho (mcp_description)" },
+      { code: "abertura_encerramento_padrao", name: "Abertura e encerramento padrão" },
+    ],
+  },
+  {
+    code: "acuracidade",
+    name: "Acuracidade",
+    weight: 25,
+    criteria: [
+      { code: "fatos_e_politicas_corretos", name: "Fatos e políticas de channel_custom (valores, dias/horários, convênio, inclusos, parcelamento, endereço)" },
+      { code: "datas_horas_coerentes", name: "Datas e horas coerentes" },
+      { code: "agendamento_bate_com_agenda", name: "Agendamento informado bate com a agenda (crítico)" },
+      { code: "nao_promete_o_que_nao_controla", name: "Não promete o que não controla" },
+    ],
+  },
+  {
+    code: "responsividade",
+    name: "Responsividade",
+    weight: 15,
+    criteria: [
+      { code: "nenhuma_pergunta_sem_resposta", name: "Nenhuma pergunta sem resposta" },
+      { code: "tempos_dentro_do_limiar", name: "frt_min e max_gap_min dentro do limiar" },
+      { code: "retorno_apos_vou_verificar", name: "'Vou verificar' seguido de retorno efetivo" },
+      { code: "ultima_mensagem_respondida", name: "Última mensagem do lead respondida" },
+    ],
+  },
+  {
+    code: "cordialidade_linguagem",
+    name: "Cordialidade & linguagem da marca",
+    weight: 15,
+    criteria: [
+      { code: "persona_e_tom", name: "Persona e tom de channel.identity" },
+      { code: "lexico_obrigatorio_proibido", name: "Léxico obrigatório/proibido" },
+      { code: "clareza_objetividade", name: "Clareza e objetividade" },
+      { code: "ortografia", name: "Ortografia" },
+      { code: "empatia_momento_sensivel", name: "Empatia em momento sensível" },
+    ],
+  },
+];
+
+// ───────── Limiares e orcamentos da plataforma ─────────
+
+/** Limiares/orcamentos default do CSQ (plataforma, nao por tenant na F1). */
+export const CSQ_DEFAULTS = {
+  /** FRT liquido acima disso conta como atraso na rubrica (minutos). */
+  frt_min_warn: 15,
+  /** Maior espera acima disso gera SLA_RESPOSTA_ALTO severidade `media`. */
+  max_gap_min_medium: 60,
+  /** Maior espera acima disso gera SLA_RESPOSTA_ALTO severidade `alta`. */
+  max_gap_min_high: 240,
+  /** Tolerancia de horario ao comparar agendamento informado x agenda (min). */
+  appointment_time_tolerance_min: 15,
+  /** Janela de dias ao redor da data informada para procurar o agendamento. */
+  appointment_day_window: 1,
+  /** Janela da jornada considerada (dias). */
+  journey_days: 90,
+  /** Teto de tickets da jornada carregados por avaliacao. */
+  journey_max_tickets: 20,
+  /** Teto de mensagens do artefato de transcricao. */
+  transcript_max_messages: 500,
+  /** Teto de bytes do artefato de transcricao. */
+  transcript_max_bytes: 200000,
+  /** Atraso da rechecagem agendada da agenda (minutos apos closed_at). */
+  recheck_delay_min: 30,
+} as const;
+
+// ───────── Evidencia ─────────
+
+/** Evidencia citada pelo juiz ou pelo codigo. O `message_id` DEVE existir na
+ *  transcricao entregue ao juiz; o codigo descarta evidencia invalida. */
+export interface ICsqEvidence {
+  message_id: string;
+  ticket_id: string;
+  ts: Date;
+  excerpt: string;
+}
+
+// ───────── Alertas ─────────
+
+/** Alerta do laudo (report-spec §6). `fingerprint` =
+ *  sha1(code|subtype|target|evidence.message_id) e a chave de dedupe e de ciclo
+ *  de vida entre avaliacoes (adendo §G). */
+export interface ICsqAlert {
+  code: CsqAlertCode;
+  subtype?: CsqAlertSubtype;
+  severity: CsqSeverity;
+  source: CsqAlertSource;
+  scope: CsqAlertScope;
+  status: CsqAlertLifecycle;
+  fingerprint: string;
+  title: string;
+  evidence: ICsqEvidence[];
+  /** Texto de acao sugerida. Na F1 e apenas texto: nao cria task nem acao. */
+  suggested_action?: string;
+  /** So em alertas de agenda: estado da rechecagem agendada (adendo §B). */
+  verification?: CsqVerificationState;
+  /** Instante em que a rechecagem deve rodar (closed_at + recheck_delay_min). */
+  recheck_after?: Date;
+  /** Ticket em que o alerta foi constatado como resolvido. */
+  resolved_in_ticket?: string;
+  /** Ticket em que o alerta apareceu pela primeira vez (herdado x novo). */
+  first_seen_ticket_id: string;
+  created_at: Date;
+}
+
+// ───────── Indicadores (report-spec §3) ─────────
+
+/** Indicadores quantitativos calculados por codigo, por lente
+ *  ("neste atendimento" e "na jornada"). `null` = nao aplicavel a lente ou
+ *  indisponivel (ex.: metricas liquidas sem horario comercial configurado). */
+export interface ICsqIndicatorsSet {
+  /** 1a mensagem do lead -> 1a resposta humana (liquido). */
+  frt_min: number | null;
+  /** Mediana de "pergunta do lead -> proxima resposta humana" (liquido). */
+  art_median_min: number | null;
+  /** p90 de "pergunta do lead -> proxima resposta humana" (liquido). */
+  art_p90_min: number | null;
+  /** Maior espera do lead por resposta humana (liquido). */
+  max_gap_min: number | null;
+  /** Perguntas do lead sem resposta humana. */
+  unanswered_questions: number | null;
+  /** A ultima mensagem do lead ficou sem resposta e o ticket fechou. */
+  last_message_unanswered: boolean | null;
+  /** 1a mensagem do lead -> 1a oferta concreta de horario (claim do juiz). */
+  time_to_first_offer_min: number | null;
+  /** 1o contato -> agendamento registrado na agenda. */
+  time_to_conversion_h: number | null;
+  /** Existe agendamento na agenda apos o 1o contato. */
+  converted: boolean | null;
+  messages_in: number | null;
+  messages_out_human: number | null;
+  messages_out_auto: number | null;
+  messages_out_ai: number | null;
+  /** Numero de humanos distintos que responderam. */
+  attendants_distinct: number | null;
+  tickets_count: number | null;
+  reopen_count: number | null;
+  transfer_count: number | null;
+  /** Tickets sem nenhuma mensagem humana. */
+  automation_only_tickets: number | null;
+  /** Audios do lead sem transcricao (reduz `confidence`). */
+  audio_in_untranscribed: number | null;
+  /** Dias desde a ultima mensagem do lead (indicador de reativacao). */
+  silence_days_since_last_inbound: number | null;
+  /** Mensagens humanas/templates apos o ultimo inbound. */
+  reactivation_attempts: number | null;
+  /** `true` quando o conjunto usa heuristica da F0 (ex.: pergunta do lead
+   *  detectada por "?" em vez do claim `question_requires_answer` do juiz). */
+  provisional?: boolean;
+}
+
+/** As duas lentes do laudo. */
+export interface ICsqIndicators {
+  ticket: ICsqIndicatorsSet;
+  journey: ICsqIndicatorsSet;
+}
+
+// ───────── Estado do lead (report-spec §2.3) ─────────
+
+/** Campo do Estado do lead com valor unico. */
+export interface ICsqLeadStateField {
+  value: string | null;
+  evidence: ICsqEvidence[];
+}
+
+/** Campo do Estado do lead com multiplos itens (restricoes, promessas...). */
+export interface ICsqLeadStateListField {
+  value: string[];
+  evidence: ICsqEvidence[];
+}
+
+/** Premissas extraidas pelo juiz e guardadas pelo codigo. E este bloco que o
+ *  proximo fechamento recebe como contexto, no lugar de reler toda a jornada. */
+export interface ICsqLeadState {
+  /** Quem fala x quem e o paciente. */
+  speaker_vs_patient: ICsqLeadStateField;
+  /** Queixa / procedimento buscado. */
+  complaint_or_procedure: ICsqLeadStateField;
+  /** Medica/profissional pretendido. */
+  preferred_professional: ICsqLeadStateField;
+  /** Primeira consulta ou ja e paciente (tag/qualificacao + conversa). */
+  patient_status: ICsqLeadStateField;
+  /** Convenio mencionado. */
+  insurance: ICsqLeadStateField;
+  /** Restricoes declaradas (dias, horarios, local, condicao de saude). */
+  constraints: ICsqLeadStateListField;
+  /** Preco informado (valor, forma, parcelas, o que inclui). */
+  price_informed: ICsqLeadStateField;
+  /** Agendamento informado ao lead (data, hora, profissional, modalidade). */
+  appointment_informed: ICsqLeadStateField;
+  /** Promessas da secretaria (o que, prazo). */
+  promises: ICsqLeadStateListField;
+  /** Perguntas do lead ainda sem resposta. */
+  open_questions: ICsqLeadStateListField;
+  /** Objecoes apresentadas e como foram tratadas. */
+  objections: ICsqLeadStateListField;
+  /** Dados obrigatorios coletados (x dicionario `capture-data`). */
+  required_data_collected: ICsqLeadStateListField;
+}
+
+// ───────── Claims (report-spec §5) ─────────
+
+/** "Informei agendamento em D/H com o profissional P". */
+export interface ICsqClaimAppointmentInformed {
+  type: "appointment_informed";
+  /** Data informada (YYYY-MM-DD, TZ do tenant). */
+  date: string;
+  /** Hora informada (HH:mm), quando houve. */
+  time?: string;
+  professional?: string;
+  modality?: string;
+  evidence: ICsqEvidence[];
+}
+
+/** "Prometi X ate quando". */
+export interface ICsqClaimPromise {
+  type: "promise";
+  what: string;
+  /** Prazo declarado, em texto ("de imediato", "ate amanha"). */
+  due?: string;
+  evidence: ICsqEvidence[];
+}
+
+/** "Coletei os dados A, B". */
+export interface ICsqClaimDataCollected {
+  type: "data_collected";
+  fields: string[];
+  evidence: ICsqEvidence[];
+}
+
+/** "O roteiro exige coletar os dados A, B" (adendo §C: o juiz declara o que o
+ *  roteiro exige; o codigo confronta com `lead.capture_data`). */
+export interface ICsqClaimRequiredData {
+  type: "required_data";
+  fields: string[];
+  evidence: ICsqEvidence[];
+}
+
+/** "Desfecho: agendou / desistiu por valor / duvida medica...". */
+export interface ICsqClaimOutcome {
+  type: "outcome";
+  outcome: string;
+  /** Codigo de fechamento que o juiz considera coerente com o desfecho. */
+  expected_close_code?: string;
+  evidence: ICsqEvidence[];
+}
+
+/** "A pergunta do lead em M exigia resposta". */
+export interface ICsqClaimQuestionRequiresAnswer {
+  type: "question_requires_answer";
+  message_id: string;
+  question: string;
+  evidence: ICsqEvidence[];
+}
+
+/** "1a oferta concreta de horario em M". */
+export interface ICsqClaimFirstConcreteOffer {
+  type: "first_concrete_offer";
+  message_id: string;
+  evidence: ICsqEvidence[];
+}
+
+/** "Lead e paciente / primeira consulta". */
+export interface ICsqClaimPatientStatus {
+  type: "patient_status";
+  status: "first_visit" | "existing_patient" | "unknown";
+  evidence: ICsqEvidence[];
+}
+
+/** "Informei preco X na forma Y". */
+export interface ICsqClaimPriceInformed {
+  type: "price_informed";
+  amount?: string;
+  payment_method?: string;
+  installments?: string;
+  includes?: string;
+  evidence: ICsqEvidence[];
+}
+
+/** Uniao discriminada por `type` — o juiz extrai, o codigo verifica (§5). */
+export type ICsqClaim =
+  | ICsqClaimAppointmentInformed
+  | ICsqClaimPromise
+  | ICsqClaimDataCollected
+  | ICsqClaimRequiredData
+  | ICsqClaimOutcome
+  | ICsqClaimQuestionRequiresAnswer
+  | ICsqClaimFirstConcreteOffer
+  | ICsqClaimPatientStatus
+  | ICsqClaimPriceInformed;
+
+export type CsqClaimType = ICsqClaim["type"];
+
+/** Linha da tabela "o que foi dito x o que consta" (report-spec §2.5). */
+export interface ICsqCrossCheck {
+  claim_type: CsqClaimType;
+  /** Resultado da verificacao por codigo. */
+  result: "match" | "mismatch" | "missing" | "inconclusive";
+  /** O que foi dito (resumo do claim). */
+  expected: string;
+  /** O que consta no sistema. */
+  found: string | null;
+  /** Alerta gerado por esta verificacao, quando houve. */
+  alert_code?: CsqAlertCode;
+  note?: string;
+}
+
+// ───────── Avaliacao (report-spec §4) ─────────
+
+/** Nota de um criterio. Todo criterio < 100 exige evidencia valida; sem ela o
+ *  codigo zera para `null` e tira do denominador. */
+export interface ICsqCriterionScore {
+  pillar: CsqPillarCode;
+  criterion: string;
+  score: CsqCriterionScore;
+  evidence: ICsqEvidence[];
+  note?: string;
+}
+
+/** Cobertura de criterios de um pilar (quantos foram pontuados x total). */
+export interface ICsqPillarCoverage {
+  scored: number;
+  total: number;
+}
+
+/** Nota do pilar = media dos criterios nao-N/A. `null` = pilar sem criterio
+ *  pontuavel (sai do denominador do score). */
+export interface ICsqPillarScore {
+  pillar: CsqPillarCode;
+  score: number | null;
+  coverage: ICsqPillarCoverage;
+}
+
+/** Resultado do `computeScore`. `score` = jornada (decisao do usuario);
+ *  `ticket_score` = so criterios com evidencia no ticket fechado (Q11=A). */
+export interface ICsqEvaluation {
+  pillars: ICsqPillarScore[];
+  score: number | null;
+  ticket_score: number | null;
+  status: CsqStatus;
+  /** Codigos de alerta que caracterizaram auto-fail nesta avaliacao. */
+  auto_fail: CsqAlertCode[];
+  escalate: {
+    value: boolean;
+    reasons: string[];
+  };
+}
+
+// ───────── Atribuicao e cobertura (adendo §E e §G) ─────────
+
+/** Humano que escreveu no ticket/jornada. Sem agregados por pessoa na F1. */
+export interface ICsqContributor {
+  user_id: string;
+  name: string;
+  messages_in_ticket: number;
+  messages_in_journey: number;
+}
+
+/** Quanto da jornada e da rubrica a avaliacao conseguiu cobrir. A UI avisa
+ *  quando a cobertura fica abaixo de 50%. */
+export interface ICsqCoverage {
+  /** `single` = apenas a thread do ticket fechado (unico modo na F1). */
+  threads: "single" | "all";
+  tickets_covered: number;
+  tickets_total: number;
+  /** Mensagens cortadas por orcamento de tokens/bytes. */
+  messages_truncated: number;
+  criteria_scored_by_pillar: Record<string, ICsqPillarCoverage>;
+}
+
+/** Sinalizacao de dado ausente que degrada a avaliacao (adendo §G). */
+export interface ICsqDataQuality {
+  /** Binding sem regra de horario: metricas liquidas ficam `null`. */
+  missing_business_hours?: boolean;
+  /** Roteiro nao configurado: pilar Roteiro forcado a N/A. */
+  missing_prompt_stack?: boolean;
+  /** Agenda indisponivel: verificacoes de agendamento ficam inconclusivas. */
+  missing_calendar?: boolean;
+  [key: string]: boolean | undefined;
+}
+
+// ───────── Veredito humano (adendo §D / Q9=A) ─────────
+
+/** Concordo/Discordo do supervisor + alertas marcados como falsos. Alimenta o
+ *  conjunto de calibracao (metricas na F2). */
+export interface ICsqReview {
+  verdict: CsqReviewVerdict;
+  /** Fingerprints dos alertas marcados como falso positivo. */
+  false_alert_fingerprints: string[];
+  note?: string;
+  reviewer_login_id: string;
+  reviewed_at: Date;
+}
+
+// ───────── Trilha e denormalizacao ─────────
+
+/** Entrada da trilha do lead (so tendencia; a serie completa vai para o BQ). */
+export interface ICsqTrailEntry {
+  ticket_id: string;
+  closed_at: Date;
+  evaluated_at: Date;
+  score: number | null;
+  status: CsqStatus;
+  alerts_critical: number;
+  alerts_new: number;
+  alerts_resolved: number;
+}
+
+/** Resumo denormalizado gravado em `ticket.csq` (fila e listagem do Omni). */
+export interface ICsqTicketSummary {
+  score: number | null;
+  status: CsqStatus;
+  alerts_critical_open: number;
+  evaluated_at: Date;
+  rubric_version: string;
+  lead_id: string;
+}
+
+// ───────── Transcricao entregue ao juiz ─────────
+
+/** Mensagem rotulada da conversa do lead. `unattributed` marca outbound sem
+ *  `created_by` (atribuido a secretaria do canal por default). */
+export interface ICsqTranscriptMessage {
+  message_id: string;
+  ticket_id: string;
+  ts: Date;
+  author_kind: CsqAuthorKind;
+  author_label: string;
+  type: string;
+  text: string;
+  unattributed?: boolean;
+}
+
+// ───────── Saida do juiz ─────────
+
+/** Uso de tokens da chamada ao juiz (acumulado das tentativas). */
+export interface ICsqLlmUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_tokens?: number;
+  cache_creation_tokens?: number;
+  /** Tentativas gastas. Contrato: <= 2 (1 retry por falha de schema). */
+  rounds?: number;
+}
+
+/** Saida estruturada da tool `submit_csq_evaluation`. O juiz NAO recebe tools
+ *  de leitura e nao decide o score final: so pontua, extrai e cita evidencia. */
+export interface ICsqJudgeOutput {
+  summary: string;
+  lead_state: ICsqLeadState;
+  claims: ICsqClaim[];
+  criteria: ICsqCriterionScore[];
+  /** So alertas de fonte `llm` ou `hybrid`; os deterministicos vem do codigo. */
+  alerts: ICsqAlert[];
+  /** Fingerprints de alertas anteriores que este atendimento resolveu.
+   *  So resolve alertas de fonte `llm` (adendo §G). */
+  resolved_alert_ids: string[];
+  highlights: string[];
+  improvements: string[];
+  confidence: number;
+  notes?: string;
+}
+
+// ───────── Fatos do sistema (report-spec §2.4) ─────────
+
+/** Agendamento do(s) paciente(s) vinculado(s) ao lead. */
+export interface ICsqAppointmentFact {
+  id: string;
+  calendar_id: string;
+  patient_id?: string;
+  start_at: Date;
+  end_at?: Date;
+  status?: string;
+  status_base?: string;
+  professional_name?: string;
+  modality?: string;
+  created_at?: Date;
+}
+
+/** Sobreposicao detectada entre agendamentos do mesmo profissional. */
+export interface ICsqOverlapFact {
+  professional_name?: string;
+  appointment_ids: string[];
+  start_at: Date;
+  end_at: Date;
+}
+
+/** Ticket anterior da jornada (motivo, quem fechou). */
+export interface ICsqPreviousTicketFact {
+  ticket_id: string;
+  closed_at?: Date;
+  close_code?: string;
+  close_name?: string;
+  closed_by_name?: string;
+  messages_count?: number;
+}
+
+/** NF ou link de pagamento ligado a um agendamento. */
+export interface ICsqBillingFact {
+  id: string;
+  kind: "invoice" | "payment_link";
+  appointment_id?: string;
+  status?: string;
+  /** Ha envio registrado ao lead (evo_chat.notifications / evo_chat_sent). */
+  sent?: boolean;
+  sent_at?: Date;
+}
+
+/** Bloco "Fatos do sistema" — tudo lido do Firestore antes da chamada ao juiz
+ *  (principio §I: contexto pre-hidratado, zero rounds de descoberta). */
+export interface ICsqSystemFacts {
+  appointments: ICsqAppointmentFact[];
+  overlaps: ICsqOverlapFact[];
+  tags: string[];
+  qualification: string | null;
+  dist_channel: string | null;
+  capture_data: Record<string, unknown> | null;
+  invoices: ICsqBillingFact[];
+  payment_links: ICsqBillingFact[];
+  previous_tickets: ICsqPreviousTicketFact[];
+}
+
+// ───────── Cabecalho do laudo (report-spec §2.1) ─────────
+
+/** Lead avaliado. `phone` e mascarado na projecao da fila (adendo §F). */
+export interface ICsqReportLead {
+  name: string | null;
+  phone: string | null;
+}
+
+/** Paciente vinculado ao lead. */
+export interface ICsqReportPatient {
+  id: string;
+  name: string | null;
+}
+
+/** Atendente humano que aparece no cabecalho. */
+export interface ICsqReportAttendant {
+  user_id: string;
+  name: string | null;
+}
+
+export interface ICsqReportHeader {
+  lead: ICsqReportLead;
+  patients: ICsqReportPatient[];
+  attendants: ICsqReportAttendant[];
+  /** 1a mensagem considerada -> fechamento. */
+  period: { from: Date | null; to: Date | null };
+  tickets_count: number;
+}
+
+/** Ticket que disparou a avaliacao. */
+export interface ICsqEvaluatedFor {
+  ticket_id: string;
+  closed_at: Date;
+  close: {
+    code?: string | null;
+    name?: string | null;
+    type_code?: string | null;
+    notes?: string | null;
+  };
+  closed_by_user_id: string | null;
+  closed_by_name: string | null;
+}
+
+/** Por que este fechamento foi considerado elegivel (gate). */
+export interface ICsqEligibility {
+  csq_mode: CsqMode;
+  eligible_calendar_ids: string[];
+  has_human_message: boolean;
+  reason?: string;
+}
+
+/** Contagem de alertas do laudo (usada pela fila e pelos indices). */
+export interface ICsqAlertCounts {
+  alerts_open: number;
+  alerts_critical_open: number;
+  alerts_new: number;
+  alerts_resolved: number;
+}
+
+// ───────── Ledger de execucao (adendo §A) ─────────
+
+/** `tenants/{t}/apps/evo-csq/runs/{eventId}` — idempotencia e retry do
+ *  pipeline. Run `done` faz o handler dar ACK imediato. */
+export interface ICsqRun extends IFireDoc {
+  /** `${ticketId}:${closedAt ISO}` — id do doc e chave de idempotencia. */
+  event_id: string;
+  status: CsqRunStatus;
+  attempts: number;
+  started_at: Date;
+  finished_at?: Date;
+  error?: string;
+  phase: CsqPhase;
+  evaluation_id?: string;
+  /** `true` quando a linha do BigQuery ainda nao foi publicada. */
+  bq_pending?: boolean;
+  /** TTL do Firestore (+30 dias). */
+  expires_at: Date;
+}
+
+// ───────── Laudo corrente por lead ─────────
+
+/** `tenants/{t}/apps/evo-csq/lead-reports/{leadId}` — relatorio corrente,
+ *  sobrescrito a cada fechamento humano elegivel. Nao ha historico de laudos
+ *  no Firestore: a serie completa vai para o BigQuery e a tendencia fica em
+ *  `trail[]`. */
+export interface ICsqLeadReport extends IFireDoc {
+  model_ver: number;
+  lead_id: string;
+  contact_id: string;
+  thread_id: string;
+  department_id: string;
+  department_name: string | null;
+  channel_id: string | null;
+  phase: CsqPhase;
+  rubric_version: string;
+  /** Modelo do juiz usado (null na F0). */
+  model: string | null;
+  /** Versao do prompt do juiz (rubrica + instrucoes de slots). */
+  prompt_version: string | null;
+  evaluated_at: Date;
+  /** Ultimo `event_id` processado — corta redelivery do Pub/Sub. */
+  last_event_key: string;
+  /** Id deterministico da avaliacao (mesmo id no BigQuery). */
+  evaluation_id: string;
+  /** Incrementado a cada regravacao do mesmo `evaluation_id` (rechecagem). */
+  version: number;
+
+  evaluated_for: ICsqEvaluatedFor;
+  header: ICsqReportHeader;
+  eligibility: ICsqEligibility;
+  indicators: ICsqIndicators;
+  system_facts: ICsqSystemFacts;
+
+  summary: string | null;
+  lead_state: ICsqLeadState | null;
+  claims: ICsqClaim[];
+  cross_checks: ICsqCrossCheck[];
+  /** Notas por critério (saída do juiz, com evidência) — persistidas para a UI expandir os pilares. */
+  criteria?: ICsqCriterionScore[];
+  evaluation: ICsqEvaluation;
+  alerts: ICsqAlert[];
+  counts: ICsqAlertCounts;
+  /** Espelho de `counts.alerts_critical_open > 0` (campo para indice). */
+  has_critical_open: boolean;
+
+  highlights: string[];
+  improvements: string[];
+  confidence: number;
+
+  /** Quem escreveu no ticket e na jornada (adendo §E). */
+  contributors: ICsqContributor[];
+  /** Preenchido so quando um unico humano escreveu no ticket fechado. */
+  primary_agent_id: string | null;
+  coverage: ICsqCoverage;
+  data_quality?: ICsqDataQuality;
+  /** Veredito humano (adendo §D). */
+  review?: ICsqReview;
+  /** Estado da rechecagem agendada da agenda no nivel do laudo (adendo §B). */
+  verification?: CsqVerificationState;
+
+  /** Hash do snapshot de politicas (stack de prompts do tenant). */
+  policy_snapshot_hash: string | null;
+  /** Hash do snapshot dos dicionarios usados na avaliacao. */
+  dictionary_snapshot_hash: string | null;
+
+  llm_usage: ICsqLlmUsage | null;
+  cost_usd_est: number | null;
+  trail: ICsqTrailEntry[];
+  judge_error?: string;
+}