# Visão do Knowledge Graph — Mud Sentinel

**Documento:** `grafo/00-visao-do-knowledge-graph.md`  
**Versão:** 1.0.0

---

## 1. Missão do grafo

Permitir que analistas **naveguem**, **descubram** e **expliquem** conexões entre atores e fatos públicos — com lineage, vigência temporal, graus de confiança e distinção explícita entre o **observado**, o **derivado** e o **inferido por IA**.

---

## 2. Princípios invariantes

1. **Toda aresta factual carrega provenance** (`source_refs[]`, `collected_at`, `confidence`).
2. **Nó ≠ verdade absoluta** — é projeção de um Party/fato tipado identificável.
3. **Temporalidade de primeira classe** — `valid_from` / `valid_to` (ou `observed_at` quando for ponto).
4. **Tipagem fechada versionada** — edge types e node labels em taxonomia (Knowledge Base / OntologyTerm).
5. **Camadas separadas:** Observed ⊂ Derived ⊂ AI-Hypothesized ⊂ Tenant-Overlay.
6. **Explicabilidade obrigatória** para qualquer resultado mostrado como “inteligência”.
7. **Limites de expansão** (profundidade, fan-out, custo) protegem o sistema e o analista de overload.
8. **Sem PII desnecessária no grafo compartilhado** — minimização; mascaramento na UI.

---

## 3. Camadas lógicas do grafo

```text
┌─────────────────────────────────────────────────────────────┐
│ L4  TENANT OVERLAY     Cases, notas pinadas, vistas salvas  │
│     (privado por Tenant — não vaza no grafo global)         │
├─────────────────────────────────────────────────────────────┤
│ L3  AI HYPOTHESIS      Arestas candidatas / scores ML       │
│     (explícitas como hypothesised=true)                     │
├─────────────────────────────────────────────────────────────┤
│ L2  DERIVED            Mesmo telefone, mesmo endereço, …    │
│     (determinísticas ou semi; com regra + evidência)        │
├─────────────────────────────────────────────────────────────┤
│ L1  OBSERVED / FACTUAL Shareholding, Signed, BidOn, …       │
│     (diretamente sustentadas por SourceRecord)              │
├─────────────────────────────────────────────────────────────┤
│ L0  IDENTITY ANCHOR    Party nodes + Identifier hubs        │
└─────────────────────────────────────────────────────────────┘
```

**Justificativa:** misturar L3 com L1 na UI é o caminho mais curto para falsa certeza. Camadas permitem filtros e legendas.

---

## 4. Estilo de modelagem: Property Graph tipado

- **Nodes** com 1+ labels (tipo principal + facets).
- **Relationships** direcionadas, tipadas, com propriedades.
- Fatos complexos (contrato, licitação) podem ser **nós de evento/fato** (reificação) quando a cardinalidade N-ary exige (várias partes, valores, datas).

**Padrão adotado:**

| Situação | Modelagem |
|----------|-----------|
| Binário simples com vigência (sócio) | Aresta `OWNS` / `PARTNER_OF` |
| N-ário (contrato com órgão + N empresas + valor) | Nó `CONTRACT` + arestas `SIGNED_BY`, `AWARDED_TO`, `GOVERNS` |
| Atributo compartilhável (telefone, endereço) | Nó hub (`PHONE`, `ADDRESS`) + `HAS_*` |
| Lista de sanção | Nó `SANCTION_ENTRY` + `LISTED_IN` + `APPLIES_TO` |

**Justificativa da reificação:** consultas “quem mais assinou este contrato?” e evidência por fato ficam naturais; pesos e aditivos anexam-se ao nó.

---

## 5. Metadados obrigatórios

### 5.1 Em todo nó de catálogo

| Metadado | Descrição |
|----------|-----------|
| `node_id` | Identificador estável do nó no grafo |
| `label` | Tipo principal |
| `ref_type` + `ref_id` | Ponte para o aggregate SoR (Party, Contract…) |
| `display_name` | Rótulo humano |
| `collected_at` | Quando o dado entrou na plataforma |
| `source_system_codes[]` | Origens agregadas |
| `confidence` | 0–1 ou banda (high/medium/low) |
| `updated_at` | Última projeção |

### 5.2 Em toda aresta

| Metadado | Descrição |
|----------|-----------|
| `edge_id` | Identificador estável |
| `type` | Tipo taxonomado |
| `layer` | observed \| derived \| ai \| tenant |
| `valid_from` / `valid_to` | Vigência (nullable com precision) |
| `weight` | Peso analítico normalizado |
| `confidence` | Confiança da afirmação |
| `evidence_refs[]` | SourceRecord / DocumentVersion IDs |
| `inferred` | boolean |
| `rule_or_model_id` | Se derived/AI |
| `collected_at` | Momento da materialização no grafo |

---

## 6. Confiança — escala oficial

| Banda | Faixa | Uso típico |
|-------|-------|------------|
| `high` | ≥ 0.85 | Identifier forte + fonte oficial + match exato |
| `medium` | 0.55–0.84 | Fonte oficial com lacunas / match parcial |
| `low` | 0.25–0.54 | Derivado fraco / homônimo / IA |
| `speculative` | < 0.25 | Hipótese — UI obrigatoriamente marcada |

Arestas `speculative` **nunca** alimentam IntegrityScore automaticamente sem regra explícita do Tenant.

---

## 7. Frequência de atualização — classes

| Classe | Significado | Exemplos |
|--------|-------------|----------|
| `realtime_watch` | Reprojeção ao evento de domínio | Alert-driven refresh de nó sob Watch |
| `daily` | Batch diário | Portal de contratos diários |
| `weekly` | Batch semanal | Algumas bases cadastrais |
| `monthly_plus` | Mensal ou sob demanda | Listas ocasionais |
| `on_ingest` | Somente quando IngestRun publicar | Padrão factual |
| `ephemeral` | Cache de path/vista | GraphPath, expansões |

---

## 8. O que NÃO entra no grafo global

- Credenciais, sessões, secrets.
- Conteúdo completo de Completions (apenas refs se pinadas no overlay).
- Documentos binários (apenas nós leve + hash ref).
- Dados de Tenant privado sem política de overlay.

---

## 9. Objetivos analíticos suportados

1. Due diligence de contraparte (ego-network).
2. Descoberta de caminhos entre A e B.
3. Detecção de núcleos (comunidades, mesmo contato).
4. Sinais de COI e concentração (centralidade).
5. Padrões de colusão / cartel (hipótese guardada).
6. Narrativa explicável para dossiê (Explainable Graph).