# Tipos de Nós — Knowledge Graph Mud Sentinel

**Documento:** `grafo/01-tipos-de-nos.md`  
**Versão:** 1.0.0

---

## Convenções

Para cada tipo de nó:

- **Tipo do nó** — label canônico (UPPER_SNAKE)
- **Nome** — designação
- **Descrição** — significado
- **Atributos principais** — propriedades do nó (conceituais)
- **Identificador único** — chave de identidade no grafo
- **Origem do dado** — Bounded Context / processo
- **Frequência de atualização** — classe (§ visão)
- **Grau de confiança** — como é atribuído
- **Data de coleta** — campo `collected_at` / política
- **Fonte da informação** — `source_system` / SourceRecord

Nós são agrupados em famílias: Atores, Locais & Contatos, Fatos públicos, Restrições & Política, Identidade & Provenance, Overlay analítico.

---

## A. Atores

### PERSON

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PERSON` |
| **Nome** | Pessoa |
| **Descrição** | Pessoa física como ator do catálogo público/analítico. |
| **Atributos principais** | `party_id`, `full_name`, `name_normalized`, `birth_year?`, `nationality?`, `status`, `pep_flag_summary?` |
| **Identificador único** | `node_id` = `person:{party_id}` (UUID Party) |
| **Origem** | People / Core |
| **Frequência** | `on_ingest` (+ `realtime_watch` se sob watch) |
| **Confiança** | high se Identifier forte; medium se só nome; low se match fuzzy |
| **Data de coleta** | `collected_at` do último SourceRecord agregado |
| **Fonte** | Cadastros públicos, QSA (sócio PF), listas PEP, órgãos oficiais |

### COMPANY

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `COMPANY` |
| **Nome** | Empresa / Organização privada |
| **Descrição** | Pessoa jurídica ou organização empresária. |
| **Atributos principais** | `party_id`, `legal_name`, `trade_name`, `legal_nature`, `primary_cnae`, `status`, `founded_on?` |
| **Identificador único** | `company:{party_id}` |
| **Origem** | Companies / Core |
| **Frequência** | `on_ingest` / tipicamente `daily`–`weekly` conforme fonte |
| **Confiança** | high com Identifier empresarial válido; medium se razão social apenas |
| **Data de coleta** | do snapshot mais recente |
| **Fonte** | Registros empresariais públicos, portais de contratos (como fornecedor) |

### GOVERNMENT_BODY

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `GOVERNMENT_BODY` |
| **Nome** | Órgão / ente público |
| **Descrição** | Órgão da administração (federal/estadual/municipal/autarquia etc.). Inclui o sentido de *Public Agency*. |
| **Atributos principais** | `party_id`, `official_name`, `sphere`, `body_type`, `jurisdiction_code`, `status` |
| **Identificador único** | `gov:{party_id}` |
| **Origem** | Government / Core |
| **Frequência** | `monthly_plus` ou `on_ingest` |
| **Confiança** | high (fontes institucionais) |
| **Data de coleta** | registro institucional |
| **Fonte** | Portais oficiais, SIAFI-like, transparência |

> Alias de linguagem: **PUBLIC_AGENCY** = mesmo label `GOVERNMENT_BODY` com `body_type` especializado (evita duplicar tipos).

### PUBLIC_AGENT

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PUBLIC_AGENT` |
| **Nome** | Agente público |
| **Descrição** | Facet/nó de papel: Person no exercício de função pública (servidor, ordenador, autoridade). Pode ser modelado como label adicional em `PERSON` **ou** nó de papel ligado por `HOLDS_ROLE`. **Padrão:** label facet `PUBLIC_AGENT` + aresta `HOLDS_MANDATE` / `HOLDS_OFFICE` → mandato. |
| **Atributos principais** | `person_party_id`, `role_title`, `jurisdiction`, `active` |
| **Identificador único** | `public_agent:{person_id}:{role_code}:{valid_from}` ou somente Person + Mandate node |
| **Origem** | Parliament / People / fontes RH públicas |
| **Frequência** | `on_ingest` |
| **Confiança** | medium–high conforme fonte |
| **Data de coleta** | mandato/fonte |
| **Fonte** | Diários oficiais, portais de transparência, casas legislativas |

### PARLIAMENT_MEMBER

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PARLIAMENT_MEMBER` |
| **Nome** | Membro do legislativo |
| **Descrição** | Facet de Person com mandato legislativo. |
| **Atributos principais** | `person_party_id`, `house`, `party_affiliation_code?`, `status` |
| **Identificador único** | `parliament_member:{person_id}` (ou via nó `MANDATE`) |
| **Origem** | Parliament |
| **Frequência** | `on_ingest` / legislativo contínuo |
| **Confiança** | high |
| **Data de coleta** | casa legislativa |
| **Fonte** | APIs/portais parlamentares |

### ECONOMIC_GROUP

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `ECONOMIC_GROUP` |
| **Nome** | Grupo econômico |
| **Descrição** | Agregado de Companies sob controle comum (observado ou derivado). |
| **Atributos principais** | `group_id`, `name`, `detection_method`, `confidence` |
| **Identificador único** | `econ_group:{group_id}` |
| **Origem** | Integrity / Graph derived |
| **Frequência** | `on_ingest` + recompute periódico |
| **Confiança** | medium (derivado) a high (fonte oficial de grupo) |
| **Data de coleta** | último recompute |
| **Fonte** | Declarações oficiais **ou** regra de ownership threshold |

### FAMILY_CLUSTER

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `FAMILY_CLUSTER` |
| **Nome** | Núcleo familiar (restrito) |
| **Descrição** | Cluster de Persons com vínculo familiar **somente** quando houver fonte pública e base legal/legitimidade de tratamento. |
| **Atributos principais** | `cluster_id`, `basis`, `legal_basis_tag`, `confidence` |
| **Identificador único** | `family:{cluster_id}` |
| **Origem** | People / Integrity (derivado controlado) |
| **Frequência** | `on_ingest` raro |
| **Confiança** | medium (fonte pública explícita) — senão **não criar** |
| **Data de coleta** | fonte familiar pública |
| **Fonte** | Declarações públicas explícitas; **nunca** inferência genética/privada |

---

## B. Locais e contatos (hubs de compartilhamento)

### ADDRESS

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `ADDRESS` |
| **Nome** | Endereço |
| **Descrição** | Endereço normalizado usado como hub “mesmo endereço”. |
| **Atributos principais** | `place_key`, `raw_address`, `normalized`, `admin_codes`, `lat?`, `lon?`, `precision` |
| **Identificador único** | `address:{hash(normalized+admin)}` |
| **Origem** | Maps / Companies snapshots / Contracts |
| **Frequência** | `on_ingest` |
| **Confiança** | high se geocoded oficial; medium se só string normalizada |
| **Data de coleta** | do SourceRecord de cadastro |
| **Fonte** | Cadastro empresarial, contratos, transparência |

### GEO_PLACE / MUNICIPALITY

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `GEO_PLACE` (subtipo `MUNICIPALITY`, `STATE`, `REGION`) |
| **Nome** | Localidade administrativa |
| **Descrição** | Município/UF/região como nó geográfico-político. |
| **Atributos principais** | `ibge_code?`, `name`, `admin_level`, `parent_code?` |
| **Identificador único** | `geo:{admin_level}:{code}` |
| **Origem** | Maps / Government |
| **Frequência** | `monthly_plus` (estável) |
| **Confiança** | high |
| **Data de coleta** | dataset geográfico oficial |
| **Fonte** | Malhas oficiais / IBGE-like |

### PHONE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PHONE` |
| **Nome** | Telefone |
| **Descrição** | Número normalizado (E.164 ou nacional) como hub. |
| **Atributos principais** | `e164`, `display`, `kind` (mobile/landline) |
| **Identificador único** | `phone:{e164}` |
| **Origem** | Cadastros públicos que exponham telefone |
| **Frequência** | `on_ingest` |
| **Confiança** | high se validado; medium se parcialmente normalizado |
| **Data de coleta** | fonte cadastral |
| **Fonte** | Somente quando **publicamente** publicado |

### EMAIL

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `EMAIL` |
| **Nome** | E-mail |
| **Descrição** | Endereço de e-mail normalizado lowercase como hub. |
| **Atributos principais** | `email`, `domain` |
| **Identificador único** | `email:{sha256(email)}` (evitar vazar em logs) |
| **Origem** | Cadastros/transparência públicos |
| **Frequência** | `on_ingest` |
| **Confiança** | high se exato |
| **Data de coleta** | fonte |
| **Fonte** | Fontes públicas apenas |

### DOMAIN

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `DOMAIN` |
| **Nome** | Domínio de Internet |
| **Descrição** | Domínio DNS associado a atores (site institucional). |
| **Atributos principais** | `domain`, `registrant_hint?` |
| **Identificador único** | `domain:{fqdn}` |
| **Origem** | Cadastros / crawling permitido |
| **Frequência** | `weekly` / `on_ingest` |
| **Confiança** | medium (WHOIS/netabilidade varia) |
| **Data de coleta** | coleta |
| **Fonte** | Sites públicos, datasets permitidos |

### IP_ADDRESS

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `IP_ADDRESS` |
| **Nome** | Endereço IP |
| **Descrição** | IP observado em contextos **lícitos e públicos** (ex.: infraestrutura publicada). Uso restrito — alto risco de ruido/ética. |
| **Atributos principais** | `ip`, `version`, `asn?` |
| **Identificador único** | `ip:{ip}` |
| **Origem** | Plugins específicos com base legal |
| **Frequência** | `ephemeral` / `on_ingest` raro |
| **Confiança** | low–medium |
| **Data de coleta** | observação |
| **Fonte** | Somente fontes autorizadas; default **desligado** |

### PROFESSIONAL_SERVICE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PROFESSIONAL_SERVICE` |
| **Nome** | Serviço profissional (contador, advogado, despachante…) |
| **Descrição** | Hub para “mesmo contador/advogado” quando a fonte pública identifica o prestador. Pode apontar para `PERSON` ou `COMPANY`. |
| **Atributos principais** | `service_kind` (accountant/lawyer/…), `display_name`, `license_id?` |
| **Identificador único** | `prof:{kind}:{party_or_license}` |
| **Origem** | QSA/contratos/anúncios públicos |
| **Frequência** | `on_ingest` |
| **Confiança** | medium |
| **Data de coleta** | fonte |
| **Fonte** | Cadastros que nomeiem responsável contábil/jurídico |

---

## C. Fatos públicos (nós reificados)

### CONTRACT

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `CONTRACT` |
| **Nome** | Contrato público |
| **Descrição** | Contrato/ajuste administrativo. |
| **Atributos principais** | `contract_id`, `external_number`, `object_summary`, `signed_on`, `start_on`, `end_on`, `total_value`, `currency`, `status` |
| **Identificador único** | `contract:{contract_id}` |
| **Origem** | Contracts |
| **Frequência** | `daily` / `on_ingest` |
| **Confiança** | high (portal oficial) |
| **Data de coleta** | publicação |
| **Fonte** | Portais de contratos / diários |

### CONTRACT_AMENDMENT

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `CONTRACT_AMENDMENT` |
| **Nome** | Aditivo contratual |
| **Descrição** | Alteração formal de CONTRACT. |
| **Atributos principais** | `amendment_id`, `sequence`, `amended_on`, `value_delta?`, `new_end_on?` |
| **Identificador único** | `contract_amd:{amendment_id}` |
| **Origem** | Contracts |
| **Frequência** | `on_ingest` |
| **Confiança** | high |
| **Data de coleta** | publicação do aditivo |
| **Fonte** | Mesmas de contratos |

### BIDDING

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `BIDDING` |
| **Nome** | Licitação / certame |
| **Descrição** | Processo licitatório. |
| **Atributos principais** | `bidding_id`, `modality`, `object_summary`, `opened_on`, `status`, `estimated_value?` |
| **Identificador único** | `bidding:{bidding_id}` |
| **Origem** | Procurement |
| **Frequência** | `daily` / `on_ingest` |
| **Confiança** | high |
| **Data de coleta** | publicação do edital/resultado |
| **Fonte** | Portais de compras públicas |

### BID

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `BID` |
| **Nome** | Proposta / participação |
| **Descrição** | Participação de um Party em certame/lote (reificação útil para valor e resultado). |
| **Atributos principais** | `bid_id`, `bid_value?`, `result`, `lot_number?` |
| **Identificador único** | `bid:{bid_id}` |
| **Origem** | Procurement |
| **Frequência** | `on_ingest` |
| **Confiança** | high–medium |
| **Data de coleta** | ata/resultado |
| **Fonte** | Compras públicas |

### TRANSFER

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `TRANSFER` |
| **Nome** | Transferência / convênio / fundo |
| **Descrição** | Fluxo de recursos entre Parties. |
| **Atributos principais** | `transfer_id`, `transfer_type`, `amount`, `currency`, `agreed_on`, `status`, `program_code?` |
| **Identificador único** | `transfer:{transfer_id}` |
| **Origem** | Transfers |
| **Frequência** | `daily`–`weekly` |
| **Confiança** | high |
| **Data de coleta** | publicação |
| **Fonte** | Portais de transferências/convénios |

### PAYMENT / PUBLIC_EXPENSE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PAYMENT` (alias de domínio para despesa liquidada/paga) |
| **Nome** | Pagamento / despesa pública |
| **Descrição** | Desembolso ou despesa modelada. |
| **Atributos principais** | `expense_id`, `amount`, `paid_on`, `nature`, `currency` |
| **Identificador único** | `payment:{expense_id}` |
| **Origem** | Transparency |
| **Frequência** | `daily` / `on_ingest` |
| **Confiança** | medium–high (heterogeneidade de portais) |
| **Data de coleta** | transparência |
| **Fonte** | Portais de transparência |

### LEGISLATIVE_BILL

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `LEGISLATIVE_BILL` |
| **Nome** | Proposição legislativa |
| **Descrição** | Projeto/ato legislativo. |
| **Atributos principais** | `bill_id`, `identifier`, `title`, `status`, `introduced_on`, `theme_tags[]` |
| **Identificador único** | `bill:{bill_id}` |
| **Origem** | Parliament |
| **Frequência** | `on_ingest` |
| **Confiança** | high |
| **Data de coleta** | casa |
| **Fonte** | Portais legislativos |

### PARLIAMENTARY_AMENDMENT

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `PARLIAMENTARY_AMENDMENT` |
| **Nome** | Emenda parlamentar |
| **Descrição** | Emenda/indicação orçamentária quando modelada (P1/P2). |
| **Atributos principais** | `amendment_id`, `year`, `amount?`, `status`, `theme?` |
| **Identificador único** | `par_amd:{amendment_id}` |
| **Origem** | Parliament / Transfers |
| **Frequência** | `on_ingest` |
| **Confiança** | medium–high |
| **Data de coleta** | publicação orçamentária |
| **Fonte** | Dados orçamentários públicos |

### MANDATE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `MANDATE` |
| **Nome** | Mandato / ofício |
| **Descrição** | Período de função oficial. |
| **Atributos principais** | `mandate_id`, `role_title`, `jurisdiction`, `start_on`, `end_on` |
| **Identificador único** | `mandate:{mandate_id}` |
| **Origem** | Parliament / Government HR públicos |
| **Frequência** | `on_ingest` |
| **Confiança** | high |
| **Data de coleta** | fonte oficial |
| **Fonte** | Casas / diários |

---

## D. Restrições e integridade

### SANCTION_LIST

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `SANCTION_LIST` |
| **Nome** | Lista de sanções/impedimentos |
| **Atributos principais** | `list_id`, `code`, `jurisdiction`, `version`, `published_on` |
| **Identificador único** | `sanction_list:{list_id}` |
| **Origem** | Sanctions |
| **Frequência** | conforme publisher (`daily`–`monthly_plus`) |
| **Confiança** | high (lista oficial) |
| **Data de coleta** | versão da lista |
| **Fonte** | Publicadores oficiais |

### SANCTION_ENTRY

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `SANCTION_ENTRY` |
| **Nome** | Entrada de sanção |
| **Atributos principais** | `entry_id`, `sanction_type`, `raw_name`, `valid_from`, `valid_to`, `match_status`, `reason?` |
| **Identificador único** | `sanction:{entry_id}` |
| **Origem** | Sanctions |
| **Frequência** | com a lista |
| **Confiança** | high na existência da entrada; **confidence do vínculo ao Party** é separado |
| **Data de coleta** | publicação |
| **Fonte** | SanctionList |

### INTEGRITY_SIGNAL

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `INTEGRITY_SIGNAL` |
| **Nome** | Sinal de integridade / COI |
| **Descrição** | Nó de anotação (não fato público) representando fator/sinal materializado para navegação. |
| **Atributos principais** | `signal_id`, `pattern_code`, `severity`, `score_contribution`, `layer=derived|rule` |
| **Identificador único** | `integrity:{signal_id}` |
| **Origem** | Integrity |
| **Frequência** | `on_ingest` / recompute |
| **Confiança** | herdada da regra |
| **Data de coleta** | `detected_at` |
| **Fonte** | RiskRule + evidências |

---

## E. Identidade e provenance

### IDENTIFIER

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `IDENTIFIER` |
| **Nome** | Identificador tipado |
| **Descrição** | Hub opcional para schemes (útil em resolução). Alternativa: propriedade em Party. **Recomendado como nó** quando múltiplos Parties disputam o mesmo valor (colisões). |
| **Atributos principais** | `scheme`, `value_normalized`, `country` |
| **Identificador único** | `id:{scheme}:{value_normalized}` |
| **Origem** | Core |
| **Frequência** | `on_ingest` |
| **Confiança** | por scheme |
| **Data de coleta** | asserção |
| **Fonte** | SourceRecord |

### SOURCE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `SOURCE` |
| **Nome** | Fonte / SourceRecord (leve) |
| **Descrição** | Nó de provenance navegável (não armazena payload). |
| **Atributos principais** | `source_record_id`, `source_system_code`, `collected_at`, `trust_level`, `external_key` |
| **Identificador único** | `source:{source_record_id}` |
| **Origem** | Core / ETL |
| **Frequência** | `on_ingest` |
| **Confiança** | = trust_level da fonte |
| **Data de coleta** | `collected_at` |
| **Fonte** | SourceSystem |

---

## F. Overlay analítico (Tenant — grafo isolado ou subgraph tagged)

### CASE_NODE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `CASE` |
| **Nome** | Dossiê |
| **Descrição** | Nós de Case **somente** no overlay do Tenant. |
| **Atributos principais** | `case_id`, `tenant_id`, `title`, `status` |
| **Identificador único** | `case:{tenant_id}:{case_id}` |
| **Origem** | Cases |
| **Frequência** | `realtime_watch` (ops analista) |
| **Confiança** | n/a (artefato de trabalho) |
| **Data de coleta** | `created_at` |
| **Fonte** | Tenant |

### DOCUMENT_NODE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `DOCUMENT` |
| **Nome** | Documento |
| **Descrição** | Referência leve a DocumentVersion no overlay/caso. |
| **Atributos principais** | `document_id`, `title`, `content_hash?` |
| **Identificador único** | `doc:{document_id}` |
| **Origem** | Documents |
| **Frequência** | sob upload |
| **Confiança** | high (integridade do hash) |
| **Data de coleta** | armazenamento |
| **Fonte** | Tenant ou espelho público |

### EVIDENCE_NODE

| Campo | Conteúdo |
|-------|----------|
| **Tipo** | `EVIDENCE` |
| **Nome** | Evidência pinada |
| **Descrição** | EvidenceItem como nó no overlay do Case. |
| **Atributos principais** | `evidence_id`, `evidence_kind`, `caption` |
| **Identificador único** | `evidence:{evidence_id}` |
| **Origem** | Evidence |
| **Frequência** | sob ação do analista |
| **Confiança** | conforme ref |
| **Data de coleta** | `captured_at` |
| **Fonte** | Case |

---

## G. Resumo de labels

```text
ACTORS:     PERSON COMPANY GOVERNMENT_BODY PUBLIC_AGENT PARLIAMENT_MEMBER
            ECONOMIC_GROUP FAMILY_CLUSTER
CONTACTS:   ADDRESS GEO_PLACE PHONE EMAIL DOMAIN IP_ADDRESS PROFESSIONAL_SERVICE
FACTS:      CONTRACT CONTRACT_AMENDMENT BIDDING BID TRANSFER PAYMENT
            LEGISLATIVE_BILL PARLIAMENTARY_AMENDMENT MANDATE
RISK:       SANCTION_LIST SANCTION_ENTRY INTEGRITY_SIGNAL
META:       IDENTIFIER SOURCE
TENANT:     CASE DOCUMENT EVIDENCE
```

**Total de tipos canônicos documentados:** 35 (+ facets de `GEO_PLACE`).