# Entidades — Atores

**Contextos:** Core, Companies, People, Government, Parliament  
**Versão:** 1.0.0

---

## Core

### Party

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Party |
| **Descrição** | Super-tipo resolvido de ator no catálogo Mud Sentinel (pessoa, empresa, órgão u outro). É a âncora de identidade analítica. |
| **Responsabilidade** | Unificar referências para grafo, busca, casos e watch sem acoplar ao subtipo. |
| **Principais atributos** | `party_id`, `party_kind` (person/company/government_body/other), `display_name`, `status` (active/merged/deprecated), `confidence`, `created_at`, `updated_at` |
| **Relacionamentos** | 1‑N Identifier; 0‑1 Person / Company / GovernmentBody (especialização); 1‑N SourceRecord links; N‑N GraphNode projection; alvo de WatchTarget e CaseEntityLink |
| **Ciclo de vida** | Candidate → Active → Merged (into surviving party) → Deprecated |
| **Produz** | `core.party.created.v1`, `core.party.merged.v1`, `core.party.updated.v1`, `core.party.deprecated.v1` |
| **Consome** | Eventos de publicação ETL (`etl.ingest_run.published.v1`) via resolução; decisões de EntityMatchCandidate |
| **Casos de uso** | UC-003, UC-004, UC-005, UC-007, UC-010 |
| **Regras** | Merge preserva lineage e redireciona IDs; nunca apagar Party referenciada por Case sem procedimento; display_name pode mudar sem mudar party_id |
| **Extensões** | Party groups (conglomerados), confiança multi-fonte, golden record scoring |

### Identifier

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Identifier |
| **Descrição** | Identificador tipado associado a um Party (CNPJ, CPF quando lícito, NIS, ID legislativo, etc.). |
| **Responsabilidade** | Suportar resolução, deduplicação e busca exata. |
| **Principais atributos** | `identifier_id`, `party_id`, `scheme` (enum), `value_normalized`, `value_display`, `country`, `valid_from`, `valid_to`, `source_record_id`, `confidence` |
| **Relacionamentos** | N‑1 Party; N‑1 SourceRecord |
| **Ciclo de vida** | Asserted → Superseded / Invalidated |
| **Produz** | `core.identifier.asserted.v1`, `core.identifier.invalidated.v1` |
| **Consome** | Publicações de Companies/People/Government |
| **Casos de uso** | UC-003, UC-004 |
| **Regras** | Normalização por scheme; unicidade scheme+value no catálogo global com tratamento de colisão via EntityMatchCandidate; mascaramento na UI conforme política |
| **Extensões** | Identifiers compostos, validação checksum |

### SourceRecord

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SourceRecord |
| **Descrição** | Evidência de origem de um fato ou atributo — o contrato de verdade documental do catálogo. |
| **Responsabilidade** | Garantir lineage, citabilidade e reprocessamento. |
| **Principais atributos** | `source_record_id`, `source_system_code`, `external_key`, `collected_at`, `observed_at`, `payload_ref`, `content_hash`, `trust_level`, `license_tag` |
| **Relacionamentos** | Originado por ETL/Crawler; referenciado por atributos e fatos tipados; citado por EvidenceItem e Citation |
| **Ciclo de vida** | Collected → Normalized → Published → Superseded |
| **Produz** | `core.source_record.published.v1`, `core.source_record.superseded.v1` |
| **Consome** | `etl.transform_job.completed.v1` |
| **Casos de uso** | UC-004, UC-008, UC-011, UC-013 |
| **Regras** | Hash obrigatório; supersede não apaga histórico; UI deve poder navegar até a fonte |
| **Extensões** | Prova de captura (screenshot hash), carimbo de tempo externo |

### EntityMatchCandidate

| Campo | Conteúdo |
|-------|----------|
| **Nome** | EntityMatchCandidate |
| **Descrição** | Hipótese de que dois registros/partys representam o mesmo ator. |
| **Responsabilidade** | Conduzir resolução assistida (auto/manual) sem colapsar identidade prematuramente. |
| **Principais atributos** | `match_id`, `left_ref`, `right_ref`, `score`, `features`, `status` (proposed/accepted/rejected), `decided_by` |
| **Relacionamentos** | Liga Party ou SourceRecord; decisão pode emitir PartyMerged |
| **Ciclo de vida** | Proposed → Accepted / Rejected / Expired |
| **Produz** | `core.entity_match.decided.v1` |
| **Consome** | Sinais de ETL e Search |
| **Casos de uso** | UC-D01 resolução de identidade (domínio) |
| **Regras** | Auto-merge só acima de limiar + regras duras (mesmo identifier scheme crítico); rejeição documentada |
| **Extensões** | Active learning, review queue por tenant enterprise |

---

## Companies

### Company

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Company |
| **Descrição** | Organização empresária ou entidade legal privada/mista modelada no catálogo (PJ). |
| **Responsabilidade** | Manter visão canônica de empresa e apontar para snapshots e vínculos societários. |
| **Principais atributos** | `company_id` (= party_id), `legal_name`, `trade_name`, `legal_nature`, `status` (active/inactive/etc.), `primary_cnae`, `founded_on`, `headquarter_geo_place_id?` |
| **Relacionamentos** | É-um Party; 1‑N CompanyRegistrationSnapshot; 1‑N Shareholding (como investee ou investor); liga PublicContract, Bidding, Transfer, SanctionEntry |
| **Ciclo de vida** | Discovered → Active profile → StatusChanged → Merged/Deprecated |
| **Produz** | `companies.company.registered.v1`, `companies.company.status_changed.v1`, `companies.company.profile_updated.v1` |
| **Consome** | `core.source_record.published.v1` (filtros de empresa) |
| **Casos de uso** | UC-003, UC-004, UC-005 |
| **Regras** | Mudanças societárias relevantes emitem eventos para Watch/Integrity; não inventar sócios sem SourceRecord |
| **Extensões** | Matriz×filial, BEPS signals, ESG flags |

### CompanyRegistrationSnapshot

| Campo | Conteúdo |
|-------|----------|
| **Nome** | CompanyRegistrationSnapshot |
| **Descrição** | Fotografia versionada dos atributos cadastrais em um instante/fonte. |
| **Responsabilidade** | Historiar evolução cadastral sem sobrescrever o passado. |
| **Principais atributos** | `snapshot_id`, `company_id`, `effective_on`, `source_record_id`, `attributes` (endereço, capital, QSA hash, etc.) |
| **Relacionamentos** | N‑1 Company; N‑1 SourceRecord |
| **Ciclo de vida** | Created → Superseded |
| **Produz** | `companies.registration_snapshot.created.v1` |
| **Consome** | — |
| **Casos de uso** | UC-004, UC-010 |
| **Regras** | Snapshot imutável; comparação diff gera TimelineEvent |
| **Extensões** | Diff estruturado tipado |

### Shareholding

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Shareholding |
| **Descrição** | Participação societária entre Parties (Person/Company → Company). |
| **Responsabilidade** | Materializar arestas societárias com vigência e percentual quando disponível. |
| **Principais atributos** | `shareholding_id`, `investor_party_id`, `investee_company_id`, `share_pct?`, `share_class?`, `role` (partner/admin/etc.), `valid_from`, `valid_to`, `source_record_id` |
| **Relacionamentos** | Projeta GraphEdge tipo `SHAREHOLDER_OF` / `ADMIN_OF`; N‑1 SourceRecord |
| **Ciclo de vida** | Active → Ended / Corrected |
| **Produz** | `companies.shareholding.opened.v1`, `companies.shareholding.closed.v1` |
| **Consome** | Snapshots QSA |
| **Casos de uso** | UC-005, UC-006, Integrity |
| **Regras** | Percentuais podem ser desconhecidos; correções criam nova versão, não editam silenciosamente; feed Watch |
| **Extensões** | Cadeias beneficial ownership estimadas |

---

## People

### Person

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Person |
| **Descrição** | Pessoa física como ator do catálogo público/analítico. |
| **Responsabilidade** | Âncora de mandatos, sanções, sócios pessoas físicas, PEPs. |
| **Principais atributos** | `person_id` (= party_id), `full_name`, `birth_date?`, `nationality?`, `status` |
| **Relacionamentos** | É-um Party; 1‑N PersonProfileSnapshot; 0‑N PoliticallyExposedFlag; Shareholding; Mandate; SanctionEntry |
| **Ciclo de vida** | Discovered → Active → Merged/Deprecated |
| **Produz** | `people.person.created.v1`, `people.person.updated.v1` |
| **Consome** | SourceRecords de pessoas |
| **Casos de uso** | UC-003–UC-008 |
| **Regras** | Minimização LGPD; atributos sensíveis classificados; homônimos exigem Identifier/Match |
| **Extensões** | Aliases, grafias alternativas |

### PersonProfileSnapshot

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PersonProfileSnapshot |
| **Descrição** | Versão histórica de atributos de Person provenientes de fonte. |
| **Responsabilidade** | Lineage e evolução temporal do perfil. |
| **Principais atributos** | `snapshot_id`, `person_id`, `source_record_id`, `effective_on`, `attributes` |
| **Relacionamentos** | N‑1 Person |
| **Ciclo de vida** | Created → Superseded |
| **Produz** | `people.profile_snapshot.created.v1` |
| **Consome** | — |
| **Casos de uso** | UC-004 |
| **Regras** | Imutável; diffs para Timeline |
| **Extensões** | Ocupações tipadas |

### PoliticallyExposedFlag

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PoliticallyExposedFlag |
| **Descrição** | Marcação de Pessoa Politicamente Exposta (PEP) ou equivalente regional. |
| **Responsabilidade** | Sinalizar risco PLD/FT e integridade com vigência e base. |
| **Principais atributos** | `pep_id`, `person_id`, `pep_level`, `basis`, `valid_from`, `valid_to`, `source_record_id`, `jurisdiction` |
| **Relacionamentos** | N‑1 Person; alimenta IntegrityFactor / RiskRule |
| **Ciclo de vida** | Active → Expired / Revoked |
| **Produz** | `people.pep.flagged.v1`, `people.pep.cleared.v1` |
| **Consome** | Listas/ETL de PEP; Mandates |
| **Casos de uso** | UC-009, UC-010 |
| **Regras** | Não rotular PEP sem base/fonte; expiração automática conforme regra jurisdicional configurável |
| **Extensões** | Relacionados PEP (familiares) quando fonte pública permitir |

---

## Government

### GovernmentBody

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GovernmentBody |
| **Descrição** | Órgão ou entidade da administração pública (união/estado/município/autarquia etc.). |
| **Responsabilidade** | Ator contratante/pagador/regulador no ecossistema de fatos públicos. |
| **Principais atributos** | `body_id` (= party_id), `official_name`, `sphere` (federal/state/municipal), `body_type`, `jurisdiction_code`, `status` |
| **Relacionamentos** | É-um Party; contrata PublicContract; abre BiddingProcess; efetiva Transfer; publica TransparencyPublication |
| **Ciclo de vida** | Active → Restructured / Extinct (merge party) |
| **Produz** | `government.body.registered.v1`, `government.body.restructured.v1` |
| **Consome** | SourceRecords institucionais |
| **Casos de uso** | UC-003–UC-005 |
| **Regras** | Esfera e jurisdição obrigatórias; reestruturações preservam histórico via snapshots/links |
| **Extensões** | Organogramas, SIAFI codes, poderes |

---

## Parliament

### ParliamentMember

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ParliamentMember |
| **Descrição** | Pessoa no exercício (ou histórico) de função parlamentar / mandato eletivo legislativo modelado. |
| **Responsabilidade** | Ligar Person a Mandate e atividades legislativas relevantes. |
| **Principais atributos** | `member_id`, `person_id`, `house` (chamber), `party_affiliation?`, `status` |
| **Relacionamentos** | N‑1 Person; 1‑N Mandate; relaciona LegislativeBill (autor/relator) |
| **Ciclo de vida** | Active → Former |
| **Produz** | `parliament.member.registered.v1` |
| **Consome** | Dados legislativos ETL |
| **Casos de uso** | UC-004, Integrity (conflitos) |
| **Regras** | Membro não substitui Person; afiliação partidária é temporal |
| **Extensões** | Comissões, votações |

### Mandate

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Mandate |
| **Descrição** | Período de mandato eletivo ou função oficial modelada. |
| **Responsabilidade** | Dar vigência a papéis políticos para PEPs e conflitos. |
| **Principais atributos** | `mandate_id`, `person_id`, `role_title`, `jurisdiction`, `start_on`, `end_on`, `source_record_id` |
| **Relacionamentos** | N‑1 Person; pode gerar PoliticallyExposedFlag; TimelineEvent |
| **Ciclo de vida** | Ongoing → Ended / Annulled |
| **Produz** | `parliament.mandate.started.v1`, `parliament.mandate.ended.v1` |
| **Consome** | — |
| **Casos de uso** | UC-009, UC-010 |
| **Regras** | Sobreposição de mandatos permitida se real; fim gera reavaliação PEP |
| **Extensões** | Mandatos executivos em contexto próprio se separado |

### LegislativeBill

| Campo | Conteúdo |
|-------|----------|
| **Nome** | LegislativeBill |
| **Descrição** | Proposição legislativa de interesse analítico (quando ingerida). |
| **Responsabilidade** | Conectar autores e temas a Actors para análise de influência (P2). |
| **Principais atributos** | `bill_id`, `identifier`, `title`, `status`, `introduced_on`, `theme_tags[]` |
| **Relacionamentos** | N‑N ParliamentMember (autoria); OntologyTerm |
| **Ciclo de vida** | Introduced → InProcess → Approved/Rejected/Archived |
| **Produz** | `parliament.bill.status_changed.v1` |
| **Consome** | ETL legislativo |
| **Casos de uso** | UC-D10 (horizonte) |
| **Regras** | Não interpretar voto como fato de corrupção; apenas dados declarados |
| **Extensões** | Emendas, relatorias, tramitação completa |