# Relacionamentos — Knowledge Graph Mud Sentinel

**Documento:** `grafo/02-relacionamentos.md`  
**Versão:** 1.0.0

---

## Convenções

Para cada relacionamento:

| Campo | Significado |
|-------|-------------|
| **Nome** | Tipo canônico `UPPER_SNAKE` |
| **Direção** | `FROM → TO` |
| **Cardinalidade** | ex.: N:1, N:M |
| **Peso** | política de `weight` (0–1 ou escala) |
| **Evidência necessária** | o que valida a aresta |
| **Fonte** | origem típica |
| **Grau de confiança** | política |
| **Observado vs inferido** | `observed` / `derived` / `ai` |

Camada padrão abaixo = **L1 Observed**, salvo indicação.

---

## 1. Atores ↔ Atores / papéis

### OWNS

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `OWNS` |
| **Direção** | `PERSON\|COMPANY → COMPANY` |
| **Cardinalidade** | N:M |
| **Peso** | `share_pct/100` se conhecido; senão `0.5` baseline ownership |
| **Evidência** | SourceRecord de QSA / acta; `share_pct?`, vigência |
| **Fonte** | Companies / Shareholding |
| **Confiança** | high se Identifier+QSA; medium se só nome |
| **Modo** | **observed** |

### PARTNER_OF / HAS_PARTNER

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `PARTNER_OF` (inversa UI: HAS_PARTNER) |
| **Direção** | `PERSON\|COMPANY → COMPANY` |
| **Cardinalidade** | N:M |
| **Peso** | por papel (sócio admin > sócio quotista desconhecido) |
| **Evidência** | QSA role |
| **Fonte** | Companies |
| **Confiança** | high/medium |
| **Modo** | observed |

### ADMIN_OF

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `ADMIN_OF` |
| **Direção** | `PERSON → COMPANY` |
| **Cardinalidade** | N:M |
| **Peso** | 0.8 default (controle operacional) |
| **Evidência** | administrador/diretor em fonte |
| **Fonte** | Companies |
| **Confiança** | high |
| **Modo** | observed |

### RELATED_TO

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `RELATED_TO` |
| **Direção** | `PERSON → PERSON` |
| **Cardinalidade** | N:M (simetrizável) |
| **Peso** | por `relation_kind` (spouse/sibling/associate…) |
| **Evidência** | Fonte pública explícita do vínculo; `legal_basis_tag` |
| **Fonte** | Declarações públicas / bases autorizadas |
| **Confiança** | medium (nunca speculative silenciosa) |
| **Modo** | observed **somente** com base; senão **proibido** |

### MEMBER_OF_GROUP

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `MEMBER_OF_GROUP` |
| **Direção** | `COMPANY → ECONOMIC_GROUP` |
| **Cardinalidade** | N:1 (ou N:M se múltiplas hipóteses) |
| **Peso** | confidence do clustering |
| **Evidência** | regra de ownership / declaração oficial |
| **Fonte** | Derived Integrity ou fonte oficial |
| **Confiança** | medium–high |
| **Modo** | observed **ou** derived |

### MEMBER_OF_FAMILY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `MEMBER_OF_FAMILY` |
| **Direção** | `PERSON → FAMILY_CLUSTER` |
| **Cardinalidade** | N:1 |
| **Peso** | confidence |
| **Evidência** | fonte pública de parentesco + base legal |
| **Fonte** | restrito |
| **Confiança** | medium |
| **Modo** | observed (estrito) |

### HOLDS_MANDATE

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HOLDS_MANDATE` |
| **Direção** | `PERSON → MANDATE` |
| **Cardinalidade** | 1:N |
| **Peso** | 1.0 enquanto vigente |
| **Evidência** | SourceRecord legislativo/administrativo |
| **Fonte** | Parliament / Government |
| **Confiança** | high |
| **Modo** | observed |

### SERVES_IN

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SERVES_IN` |
| **Direção** | `MANDATE → GOVERNMENT_BODY\|GEO_PLACE` |
| **Cardinalidade** | N:1 |
| **Peso** | 1.0 |
| **Evidência** | mandato |
| **Fonte** | Parliament |
| **Confiança** | high |
| **Modo** | observed |

---

## 2. Contatos e localização

### LOCATED_AT

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `LOCATED_AT` |
| **Direção** | `COMPANY\|PERSON\|GOVERNMENT_BODY → ADDRESS` |
| **Cardinalidade** | N:M (múltiplos endereços ao longo do tempo) |
| **Peso** | 0.6 HQ; 0.3 secondary |
| **Evidência** | snapshot cadastral / contrato |
| **Fonte** | Companies / Contracts |
| **Confiança** | medium–high |
| **Modo** | observed |

### LOCATED_IN

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `LOCATED_IN` |
| **Direção** | `ADDRESS\|COMPANY\|GOVERNMENT_BODY → GEO_PLACE` |
| **Cardinalidade** | N:1 |
| **Peso** | 0.5 |
| **Evidência** | código município / geocode |
| **Fonte** | Maps |
| **Confiança** | high se código oficial |
| **Modo** | observed |

### HAS_PHONE

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_PHONE` |
| **Direção** | `COMPANY\|PERSON\|GOVERNMENT_BODY → PHONE` |
| **Cardinalidade** | N:M |
| **Peso** | 0.4 (contato fraco sozinho) |
| **Evidência** | telefone publicado |
| **Fonte** | Cadastros públicos |
| **Confiança** | high se normalizado |
| **Modo** | observed |

### HAS_EMAIL

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_EMAIL` |
| **Direção** | `*ATOR → EMAIL` |
| **Cardinalidade** | N:M |
| **Peso** | 0.45 |
| **Evidência** | e-mail publicado |
| **Fonte** | Cadastros/transparência |
| **Confiança** | high |
| **Modo** | observed |

### HAS_DOMAIN

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_DOMAIN` |
| **Direção** | `COMPANY\|GOVERNMENT_BODY → DOMAIN` |
| **Cardinalidade** | N:M |
| **Peso** | 0.5 |
| **Evidência** | site oficial declarado |
| **Fonte** | Cadastro / web permitida |
| **Confiança** | medium |
| **Modo** | observed |

### HAS_IP *(restrito)*

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_IP` |
| **Direção** | `DOMAIN\|COMPANY → IP_ADDRESS` |
| **Cardinalidade** | N:M |
| **Peso** | 0.25 (ruim; CDN shared) |
| **Evidência** | resolução DNS pública autorizada |
| **Fonte** | Plugin opcional |
| **Confiança** | low |
| **Modo** | observed (feature flag off by default) |

### HAS_PROFESSIONAL

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_PROFESSIONAL` |
| **Direção** | `COMPANY → PROFESSIONAL_SERVICE` |
| **Cardinalidade** | N:M |
| **Peso** | 0.55 |
| **Evidência** | contador/advogado nomeado em fonte |
| **Fonte** | QSA / contratos |
| **Confiança** | medium |
| **Modo** | observed |

### PROVIDED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `PROVIDED_BY` |
| **Direção** | `PROFESSIONAL_SERVICE → PERSON\|COMPANY` |
| **Cardinalidade** | N:1 |
| **Peso** | 0.7 |
| **Evidência** | identidade do prestador |
| **Fonte** | idem |
| **Confiança** | medium–high |
| **Modo** | observed |

### HAS_AGENCY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `HAS_AGENCY` |
| **Direção** | `GEO_PLACE(MUNICIPALITY) → GOVERNMENT_BODY` |
| **Cardinalidade** | 1:N |
| **Peso** | 1.0 |
| **Evidência** | vínculo jurisdicional do órgão |
| **Fonte** | Government |
| **Confiança** | high |
| **Modo** | observed |

---

## 3. Contratos, pagamentos, licitações

### SIGNED

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SIGNED` |
| **Direção** | `PUBLIC_AGENT\|PERSON\|GOVERNMENT_BODY → CONTRACT` |
| **Cardinalidade** | N:M |
| **Peso** | 0.9 se ordenador/assinante; 0.6 se testemunha |
| **Evidência** | assinatura/nome em instrumento público |
| **Fonte** | Contracts |
| **Confiança** | high–medium (OCR/nome) |
| **Modo** | observed |

### CONTRACTED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `CONTRACTED_BY` |
| **Direção** | `CONTRACT → GOVERNMENT_BODY` |
| **Cardinalidade** | N:1 |
| **Peso** | 1.0 |
| **Evidência** | órgão contratante |
| **Fonte** | Contracts |
| **Confiança** | high |
| **Modo** | observed |

### AWARDED_TO / EXECUTED

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `AWARDED_TO` (execução: `EXECUTED_BY` da Company → Contract) |
| **Direção** | `CONTRACT → COMPANY\|PERSON` **e/ou** `COMPANY → CONTRACT` via `EXECUTED` |
| **Cardinalidade** | N:M |
| **Peso** | proporcional a valor relativo do ator |
| **Evidência** | fornecedor adjudicado/contratado |
| **Fonte** | Contracts / Procurement |
| **Confiança** | high |
| **Modo** | observed |

> Uso oficial: manter **ambas** as direções só se necessárias a UX; preferir uma canônica `CONTRACT -[:AWARDED_TO]-> COMPANY` e view inversa.

### AMENDED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `AMENDED_BY` |
| **Direção** | `CONTRACT → CONTRACT_AMENDMENT` |
| **Cardinalidade** | 1:N |
| **Peso** | `|value_delta|/original` cap 1.0 |
| **Evidência** | aditivo publicado |
| **Fonte** | Contracts |
| **Confiança** | high |
| **Modo** | observed |

### PARTICIPATED_IN

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `PARTICIPATED_IN` |
| **Direção** | `COMPANY\|PERSON → BIDDING` (via `BID` reificado preferível) |
| **Cardinalidade** | N:M |
| **Peso** | 0.5 participated; 0.9 winner |
| **Evidência** | ata / resultado |
| **Fonte** | Procurement |
| **Confiança** | high |
| **Modo** | observed |

### SUBMITTED

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SUBMITTED` |
| **Direção** | `COMPANY → BID` ; `BID → BIDDING` (`PART_OF`) |
| **Cardinalidade** | N:1 cadeia |
| **Peso** | conforme result |
| **Evidência** | proposta |
| **Fonte** | Procurement |
| **Confiança** | high |
| **Modo** | observed |

### OPENED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `OPENED_BY` |
| **Direção** | `BIDDING → GOVERNMENT_BODY` |
| **Cardinalidade** | N:1 |
| **Peso** | 1.0 |
| **Evidência** | órgão licitante |
| **Fonte** | Procurement |
| **Confiança** | high |
| **Modo** | observed |

### RECEIVED (PAYMENT)

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `RECEIVED` |
| **Direção** | `COMPANY\|PERSON → PAYMENT` **ou** `PAYMENT → COMPANY` (`PAID_TO`) |
| **Cardinalidade** | N:M |
| **Peso** | log-normalizado do valor |
| **Evidência** | favorecido na despesa |
| **Fonte** | Transparency |
| **Confiança** | medium–high |
| **Modo** | observed |

### PAID_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `PAID_BY` |
| **Direção** | `PAYMENT → GOVERNMENT_BODY` |
| **Cardinalidade** | N:1 |
| **Peso** | 1.0 |
| **Evidência** | pagador |
| **Fonte** | Transparency |
| **Confiança** | high |
| **Modo** | observed |

### RELATED_CONTRACT

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SETTLES` / `RELATED_TO_CONTRACT` |
| **Direção** | `PAYMENT → CONTRACT` |
| **Cardinalidade** | N:1 |
| **Peso** | 0.8 |
| **Evidência** | referência cruzada de Instrumento |
| **Fonte** | Transparency/Contracts |
| **Confiança** | medium (nem sempre linkável) |
| **Modo** | observed ou derived (match de número) |

### GRANTED / TRANSFERRED_TO

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `TRANSFERRED_TO` |
| **Direção** | `TRANSFER → COMPANY\|GOVERNMENT_BODY\|GEO_PLACE` ; `GRANTOR` via `TRANSFERRED_FROM` |
| **Cardinalidade** | N:1 cada ponta |
| **Peso** | por valor |
| **Evidência** | instrument de transferência |
| **Fonte** | Transfers |
| **Confiança** | high |
| **Modo** | observed |

### FUNDED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `FUNDED_BY` |
| **Direção** | `CONTRACT\|TRANSFER\|PAYMENT → PARLIAMENTARY_AMENDMENT` |
| **Cardinalidade** | N:M |
| **Peso** | fração do valor quando conhecida |
| **Evidência** | vínculo orçamentário publicado |
| **Fonte** | Parliament / orçamento |
| **Confiança** | medium–high |
| **Modo** | observed |

### ALLOCATED_TO

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `ALLOCATED_TO` |
| **Direção** | `PARLIAMENTARY_AMENDMENT → GEO_PLACE(MUNICIPALITY)\|GOVERNMENT_BODY\|TRANSFER` |
| **Cardinalidade** | N:M |
| **Peso** | 0.8 |
| **Evidência** | destinação publicada |
| **Fonte** | Emendas |
| **Confiança** | medium–high |
| **Modo** | observed |

### AUTHORED

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `AUTHORED` |
| **Direção** | `PARLIAMENT_MEMBER\|PERSON → LEGISLATIVE_BILL\|PARLIAMENTARY_AMENDMENT` |
| **Cardinalidade** | N:M |
| **Peso** | 0.7 |
| **Evidência** | autoria parlamentar |
| **Fonte** | Parliament |
| **Confiança** | high |
| **Modo** | observed |

---

## 4. Sanções e integridade

### LISTED_IN

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `LISTED_IN` |
| **Direção** | `SANCTION_ENTRY → SANCTION_LIST` |
| **Cardinalidade** | N:1 |
| **Peso** | 1.0 |
| **Evidência** | membership na lista |
| **Fonte** | Sanctions |
| **Confiança** | high |
| **Modo** | observed |

### APPLIES_TO

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `APPLIES_TO` |
| **Direção** | `SANCTION_ENTRY → PERSON\|COMPANY` |
| **Cardinalidade** | N:M (ambiguidade possível) |
| **Peso** | = match confidence |
| **Evidência** | EntityMatch + identifiers |
| **Fonte** | Sanctions + Core |
| **Confiança** | variável — **sempre exibir match_status** |
| **Modo** | observed (entrada) + **derived/ai** (link ao Party) |

### FLAGS

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `FLAGS` |
| **Direção** | `INTEGRITY_SIGNAL → PERSON\|COMPANY\|CONTRACT\|…` |
| **Cardinalidade** | N:M |
| **Peso** | score_contribution normalizado |
| **Evidência** | RiskRule + source_refs |
| **Fonte** | Integrity |
| **Confiança** | herdada |
| **Modo** | derived (regra) |

### INVOLVES_PATH

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `INVOLVES_PATH` |
| **Direção** | `INTEGRITY_SIGNAL →` (metadado de path ids — ou aresta para nós do path) |
| **Cardinalidade** | 1:N |
| **Peso** | 0.6 |
| **Evidência** | GraphPath explicável |
| **Fonte** | Integrity/Graph |
| **Confiança** | medium |
| **Modo** | derived |

---

## 5. Provenance e identidade

### IDENTIFIED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `IDENTIFIED_BY` |
| **Direção** | `PERSON\|COMPANY\|GOVERNMENT_BODY → IDENTIFIER` |
| **Cardinalidade** | N:M |
| **Peso** | 1.0 para scheme crítico |
| **Evidência** | asserção Identifier |
| **Fonte** | Core |
| **Confiança** | por scheme |
| **Modo** | observed |

### SUPPORTED_BY

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SUPPORTED_BY` |
| **Direção** | `*FATO\|ARESTA-reificada → SOURCE` |
| **Cardinalidade** | N:M |
| **Peso** | trust_level |
| **Evidência** | SourceRecord |
| **Fonte** | Core/ETL |
| **Confiança** | = trust |
| **Modo** | observed |

### SAME_AS

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `SAME_AS` |
| **Direção** | `PARTY_NODE → PARTY_NODE` (após merge redirect, ou candidatos) |
| **Cardinalidade** | N:1 surviving |
| **Peso** | match score |
| **Evidência** | EntityMatch decision |
| **Fonte** | Core |
| **Confiança** | high se accepted |
| **Modo** | observed (decisão) / ai (candidato com layer=ai) |

---

## 6. Overlay Tenant

### IN_CASE

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `IN_CASE` |
| **Direção** | `PERSON\|COMPANY\|CONTRACT\|… → CASE` |
| **Cardinalidade** | N:M |
| **Peso** | 1.0 |
| **Evidência** | CaseEntityLink |
| **Fonte** | Cases |
| **Confiança** | n/a |
| **Modo** | tenant overlay |

### CITED_AS_EVIDENCE

| Campo | Conteúdo |
|-------|----------|
| **Nome** | `CITED_AS_EVIDENCE` |
| **Direção** | `SOURCE\|DOCUMENT\|CONTRACT\|… → EVIDENCE → CASE` |
| **Cardinalidade** | N:M |
| **Peso** | 1.0 |
| **Evidência** | EvidenceItem |
| **Fonte** | Evidence |
| **Confiança** | n/a |
| **Modo** | tenant overlay |

---

## 7. Catálogo rápido (L1 observados principais)

```text
PERSON|COMPANY  -OWNS/PARTNER_OF/ADMIN_OF->  COMPANY
PERSON          -RELATED_TO->                PERSON
PERSON          -HOLDS_MANDATE->             MANDATE -SERVES_IN-> BODY|GEO
ATOR            -LOCATED_AT->                ADDRESS -LOCATED_IN-> GEO_PLACE
MUNICIPALITY    -HAS_AGENCY->                GOVERNMENT_BODY
ATOR            -HAS_PHONE/EMAIL/DOMAIN->    hubs
COMPANY         -HAS_PROFESSIONAL->          PROFESSIONAL_SERVICE -PROVIDED_BY-> PERSON|COMPANY
AGENT|BODY      -SIGNED->                    CONTRACT
CONTRACT        -CONTRACTED_BY->             GOVERNMENT_BODY
CONTRACT        -AWARDED_TO->                COMPANY
CONTRACT        -AMENDED_BY->                CONTRACT_AMENDMENT
COMPANY         -PARTICIPATED_IN/SUBMITTED-> BIDDING/BID
COMPANY         -EXECUTED->                  CONTRACT
COMPANY|PERSON  -RECEIVED->                  PAYMENT -PAID_BY-> BODY
TRANSFER        -TRANSFERRED_TO/FROM->       PARTIES
CONTRACT|PAY    -FUNDED_BY->                 PARLIAMENTARY_AMENDMENT
AMENDMENT       -ALLOCATED_TO->              MUNICIPALITY|BODY
MEMBER          -AUTHORED->                  BILL|AMENDMENT
SANCTION_ENTRY  -LISTED_IN->                 SANCTION_LIST
SANCTION_ENTRY  -APPLIES_TO->                PERSON|COMPANY
PARTY           -IDENTIFIED_BY->             IDENTIFIER
FACT            -SUPPORTED_BY->              SOURCE
```

Relacionamentos **derived** e **AI** → documento [03-ia-e-derivados.md](03-ia-e-derivados.md).