# Linguagem Ubíqua — Mud Sentinel

**Arquivo:** `ubiquitous_language.md`  
**Documento oficial:** `docs/dominio/ubiquitous_language.md`  
**Versão:** 1.0.0  
**Status:** Vigente  
**Responsável:** Principal Domain Architect

---

## 1. Propósito

Este documento define a **linguagem oficial do domínio** Mud Sentinel. Todo PR, ADR, história de usuário, texto de UI (PT-BR), evento de domínio e conversa de produto/engenheira/segurança deve aderir a estes termos.

Em caso de conflito com jargão informal, **prevalece este documento** (e o [Glossário](glossario.md)).

---

## 2. Regras de uso da linguagem

1. **Um conceito, um nome.** Não inventar sinônimos locais (“dossier”, “investigation file”, “matter”) para *Case*.
2. **Qualificar ambiguidade.** Nunca dizer só “entidade”, “evento”, “cliente”, “documento” sem o termo canônico.
3. **PT-BR na UI; EN nos identificadores de modelo.** Ex.: UI “Dossiê”, modelo `Case`.
4. **Fato ≠ hipótese ≠ score ≠ caminho de grafo.** Cada um tem verbo e substantivo próprios.
5. **Fontes antes de afirmações.** Se não há `SourceRecord` (direta ou via fato tipado), não chamar de fato publicado.
6. **Tenant é o isolamento.** Dados analíticos privados sempre “do Tenant”; catálogo público é “compartilhado/read model”.
7. **IA não publica fatos.** Completions *interpretam*, *resumem* ou *hipotetizam*.
8. **Mudança de termo exige** atualização deste arquivo + glossário + revisão de UI copy.

---

## 3. Vocabulário canônico (substantivos)

### 3.1 Plataforma e acesso

| PT-BR (UI/negócio) | EN (modelo) | Definição oficial | Não confundir com |
|--------------------|-------------|-------------------|-------------------|
| Organização / Conta cliente | Tenant | Isolamento multi-tenant raiz | UserAccount |
| Espaço de trabalho | Workspace | Segmentação opcional dentro do Tenant | Tenant |
| Usuário | UserAccount | Conta de login | Person |
| Papel | Role | Conjunto de permissões | Mandate |
| Sessão | Session | Autenticação vigente | — |
| Convite | Invitation | Oferta de membership | Notification |
| Cliente de API | ApiClient | Credencial M2M | Tenant |
| Capacidade | Entitlement | Feature liberada | Feature flag de release |
| Cota | Quota | Limite quantitativo | Entitlement (binário) |
| Evento de auditoria | AuditEvent | Registro de accountability | Application log |
| Política de acesso | AccessPolicy | Configuração de Settings | RiskRule |

### 3.2 Atores do catálogo

| PT-BR | EN | Definição oficial | Não confundir com |
|-------|----|-------------------|-------------------|
| Parte / Ator resolvido | Party | Super-tipo do catálogo | UserAccount; “entity” genérico |
| Identificador | Identifier | Chave tipada (scheme+value) | party_id interno |
| Registro de origem | SourceRecord | Lineage citável publicado | RawPayload (bruto) |
| Candidato a match | EntityMatchCandidate | Hipótese de duplicidade | Merge já decidido |
| Empresa | Company | PJ no catálogo | Tenant (cliente SaaS) |
| Instantâneo cadastral | CompanyRegistrationSnapshot | Versão imutável de atributos | Case snapshot informal |
| Participação societária | Shareholding | Vínculo investidor→empresa | MembershipInterest |
| Pessoa | Person | PF no catálogo | UserAccount |
| Instantâneo de pessoa | PersonProfileSnapshot | Versão de atributos PF | — |
| Marcação PEP | PoliticallyExposedFlag | PEP com base e vigência | Role de produto |
| Órgão público | GovernmentBody | Ator institucional | Company |
| Parlamentar (membro) | ParliamentMember | Person em função legislativa | User |
| Mandato | Mandate | Vigência de função oficial | Role IAM |
| Proposição | LegislativeBill | Projeto/ato legislativo modelado | Document upload |

### 3.3 Transações e restrições públicas

| PT-BR | EN | Definição oficial |
|-------|----|-------------------|
| Contrato público | PublicContract | Ajuste administrativo tipado |
| Aditivo | ContractAmendment | Alteração formal do contrato |
| Licitação / certame | BiddingProcess | Processo de seleção |
| Lote | ProcurementLot | Parte adjudicável do certame |
| Proposta / lance | Bid | Participação de um Party |
| Publicação de transparência | TransparencyPublication | Pacote/registro de portal |
| Despesa pública | PublicExpense | Gasto modelado |
| Transferência | Transfer | Fluxo de recurso (convênio/fundo/etc.) |
| Lista de sanções | SanctionList | Conjunto versionado |
| Entrada de sanção | SanctionEntry | Restrição/impedimento linkável |

### 3.4 Análise, integridade e evidência

| PT-BR | EN | Definição oficial | Não confundir com |
|-------|----|-------------------|-------------------|
| Dossiê / Caso | Case | Aggregate de trabalho analítico do Tenant | Case jurídico externo |
| Vínculo no dossiê | CaseEntityLink | Escopo do Case | GraphEdge |
| Nota | CaseNote | Texto humano (fato referido / hipótese / todo) | Completion |
| Achado | Finding | Conclusão estruturada revisável | IntegrityScore |
| Documento | Document | Artefato versionado gerenciado | TransparencyPublication |
| Versão de documento | DocumentVersion | Bytes + hash imutáveis | — |
| Evidência | EvidenceItem | Unidade citável no Case | SourceRecord (catálogo) |
| Manifesto de evidências | EvidenceManifest | Fechamento para export | ExportPackage |
| Regra de risco | RiskRule | Lógica versionada de sinalização | AccessPolicy |
| Fator de integridade | IntegrityFactor | Contribuição explicável | Alert |
| Score de integridade | IntegrityScore | Agregação versionada | “prova” |
| Sinal de COI | ConflictOfInterestSignal | Indício de conflito de interesse | Finding confirmado |
| Interesse de vínculo | MembershipInterest | Participação não societária tipada | Shareholding |
| Nó | GraphNode | Projeção navegável | Party (SoR) |
| Aresta | GraphEdge | Relacionamento tipado projetado | CaseEntityLink |
| Caminho | GraphPath | Travessia entre nós | Prova de crime |
| Vista de grafo | GraphView | Subgrafo salvo | ExportPackage |
| Evento de linha do tempo | TimelineEvent | Marco temporal unificado | Domain Event técnico |
| Local | GeoPlace | Âncora geográfica | Tenant address billing |
| Camada de mapa | MapLayer | Conjunto geo analítico | — |
| Lista de monitoramento | Watchlist | Agrupador de alvos | SanctionList |
| Alvo monitorado | WatchTarget | Party/fato observado | Watchlist |
| Regra de alerta | AlertRule | Gatilho configurável | RiskRule |
| Alerta | Alert | Instância de notificação de mudança | Notification (canal) |
| Modelo de relatório | ReportTemplate | Estrutura versionada de saída | PromptTemplate |
| Relatório | Report | Instância gerada | Case |
| Pacote de exportação | ExportPackage | Artefato deliverable com hash | DocumentVersion avulsa |

### 3.5 Dados, busca e IA

| PT-BR | EN | Definição oficial |
|-------|----|-------------------|
| Sistema de origem | SourceSystem | Fonte lógica catalogada |
| Alvo de coleta | CrawlTarget | Locator de aquisição |
| Job de coleta | CrawlJob | Execução de crawl |
| Payload bruto | RawPayload | Original imutável |
| Job de transformação | TransformJob | Parse/normalize/validate |
| Execução de ingestão | IngestRun | Publish atômico |
| Issue de qualidade | DataQualityIssue | Defeito detectável |
| Documento de busca | SearchDocument | Projeção indexada |
| Consulta de busca | SearchQuery | Execução de search (telemetria) |
| Termo de ontologia | OntologyTerm | Vocabulário controlado |
| Artigo de conhecimento | KnowledgeArticle | Metodologia/ajuda |
| Chunk | EmbeddingChunk | Fragmento embeddado citável |
| Consulta de retrieval | RetrievalQuery | Busca semântica rastreada |
| Template de prompt | PromptTemplate | Prompt versionado |
| Completion / resposta de IA | Completion | Saída de modelo |
| Citação | Citation | Ligação Completion→fonte |
| Evento de uso | UsageEvent | Metering |
| Plugin conector | ConnectorPlugin | Extensão de fonte |
| Instalação de plugin | PluginInstallation | Ativação + config |

---

## 4. Verbos oficiais (ações de domínio)

Use estes verbos em eventos, histórias e código futuro:

| Verbo | Aplicação típica |
|-------|------------------|
| **Provision** | Tenant |
| **Invite / Accept / Revoke** | Invitation, Role |
| **Authenticate / Authorize** | Session, permissions |
| **Assert** | Identifier, atributo com fonte |
| **Publish / Supersede** | SourceRecord, IngestRun, fatos |
| **Merge / Deprecate** | Party |
| **Decide** | EntityMatchCandidate |
| **Open / Close / End** | Shareholding, Mandate |
| **Award / Cancel** | Bidding |
| **Amend** | Contract |
| **Flag / Clear** | PEP |
| **Lift** | SanctionEntry |
| **Link / Unlink** | CaseEntity, Sanction→Party |
| **Transition** | Case status |
| **Confirm / Retract** | Finding |
| **Raise / Withdraw** | IntegrityFactor, Alert |
| **Compute** | IntegrityScore, GraphPath |
| **Acknowledge** | Alert, COI signal |
| **Expand** | GraphNode |
| **Index / Retrieve** | Search, RAG |
| **Generate** | Completion, Manifest, Report |
| **Pin** | Completion → Evidence |
| **Export / Download** | ExportPackage |
| **Enqueue** | Crawl, export, jobs |
| **Record** | UsageEvent, Bid, Expense |

---

## 5. Distinções obrigatórias (cartões de decisão)

### 5.1 UserAccount vs Person

- **UserAccount** usa o produto.
- **Person** é observada no catálogo público/analítico.
- Uma Person **não** autentica; um UserAccount **não** entra no grafo societário.

### 5.2 SourceRecord vs EvidenceItem

- **SourceRecord** vive no catálogo (verdade publicada da plataforma).
- **EvidenceItem** vive no Case (o que o analista pinou para o dossiê).
- Export cita Evidence; Evidence frequentemente aponta SourceRecord.

### 5.3 RiskRule vs AlertRule

- **RiskRule** avalia integridade/risco e gera fatores/score.
- **AlertRule** decide quando **notificar** mudança para humanos.
- Podem correlacionar, mas não são a mesma coisa.

### 5.4 GraphPath vs Finding

- **GraphPath** = estrutura encontrada sob constraints.
- **Finding** = julgamento analítico humano (ou mediado) dentro do Case.
- Path pode **fundamentar** Finding; nunca o substitui sozinho na linguagem de acusação.

### 5.5 Fato vs Hipótese vs Completion

| Tipo | Quem cria | Precisa de fonte? | Pode ir ao catálogo? |
|------|-----------|-------------------|----------------------|
| Fato público | ETL/contextos de fatos | Sim (SourceRecord) | Sim |
| Hipótese | Analista (CaseNote) ou IA em mode hypothesis | Recomendável | Não |
| Completion | AI | Citações conforme mode | Não (só se pinado como Evidence no Case) |

### 5.6 Tenant vs Company

- **Tenant** paga/usa o SaaS.
- **Company** é contraparte/ator no mundo público modelado.
- Um Tenant pode *analisar* Companies; não *é* uma Company no Core.

---

## 6. Frases canônicas (exemplos certos e errados)

| Evitar | Preferir |
|--------|----------|
| “A IA descobriu que a empresa é irregular.” | “A Completion, em modo hipótese, destacou fatores X/Y com citações Z.” |
| “Provamos o vínculo no grafo.” | “Encontramos um caminho estrutural de comprimento N entre Party A e B.” |
| “O usuário João (CPF…)” misturando login e catálogo | “UserAccount joao@… analisando Person …” |
| “Evento” sem qualificar | “TimelineEvent de aditivo” / “domain event contracts.amendment.published” |
| “Documento da Receita” ambíguo | “SourceRecord da fonte X” ou “TransparencyPublication …” |
| “Score prova risco” | “IntegrityScore na faixa alta, composto pelos fatores …” |

---

## 7. Nomes de eventos (padrão linguístico)

```text
<contexto>.<agregado_ou_entidade>.<verbo_no_particípio_ou_passado>.vN
```

Exemplos corretos:

- `companies.shareholding.opened.v1`
- `cases.case.finalized.v1`
- `sanctions.entry.linked_to_party.v1`
- `ai.completion.generated.v1`
- `watch.alert.raised.v1`

Evitar: `somethingChanged`, `update`, `data`, `notify` genéricos.

---

## 8. Papéis humanos (linguagem de atores)

| Papel PT-BR | Responsabilidade em linguagem de domínio |
|-------------|------------------------------------------|
| Analista | Search, Expand, CreateCase, RequestCompletion, AddEvidence |
| Auditor | GetTimeline, Export, leitura ampla de AuditEvent do tenant |
| Admin do Tenant | Invite, ConfigureRule (quando permitido), Watchlists, Policies |
| Admin da Plataforma | RegisterPlugin, SourceSystem trust, break-glass auditado |
| Sistema (workers) | EnqueueCrawl, PublishIngestRun, Project Graph/Timeline, RaiseAlert |

---

## 9. Classificação de dados na fala do time

Ao discutir campos, sempre classificar:

- **Public catalog** — compartilhado entre tenants (read).
- **Tenant private** — Cases, Notes, Uploads, Watchlists, completions armazenadas.
- **Platform ops** — RawPayload, crawlers, DLQ.
- **Secrets** — nunca em linguagem de fato de negócio.

---

## 10. Governança deste documento

| Mudança | Processo |
|---------|----------|
| Novo termo | PR atualizando `ubiquitous_language.md` + `glossario.md` |
| Renomear conceito | ADR se impactar contextos + migration lingüística de UI |
| Conflito entre times | Domain Architect decide; registra no mapa de contextos |

**Revisão:** no mínimo a cada trimestre ou ao introduzir Bounded Context novo.

---

## 11. Referências cruzadas

- Catálogo de entidades: [entidades/](entidades/README.md)
- Bounded Contexts: [01-bounded-contexts.md](01-bounded-contexts.md)
- Mapa: [02-mapa-de-contextos.md](02-mapa-de-contextos.md)
- Glossário curto: [glossario.md](glossario.md)
- Casos de uso de produto: [../produto/02-casos-de-uso.md](../produto/02-casos-de-uso.md)