evo360-types 1.3.505 → 1.3.510

package/dist/types/evo-integrations/test-suite.ts

@@ -0,0 +1,376 @@
+// ======================================================
+// evo-integrations — bateria de regressão de adapters (feat-123)
+//
+// Porte do script `_regressao-adapters.cjs` para ferramenta de produto no Nexus.
+//
+// A ferramenta é APARTADA: roda por fora, chamando as APIs (`integrations_actions`,
+// `integrations_admin`, `integrations_sync_monitor`) exatamente como o script faz.
+// Quem orquestra a sequência é o FE; quem persiste o resultado é o BE.
+//
+// Este módulo é o contrato COMPARTILHADO entre os dois lados:
+//   · o FE monta a seleção a partir do catálogo de passos;
+//   · o BE valida a seleção contra o MESMO catálogo e calcula o veredito.
+//
+// O catálogo de defeitos CONHECIDOS não mora aqui — mora no backend do Nexus,
+// porque só ele calcula veredito (o FE apenas renderiza o que recebe).
+// ======================================================
+
+import type { IFireDoc } from "../shared";
+
+// Path: /platform/evo-integrations/test-runs/{run_id}
+export const TEST_RUNS_COLLECTION = "test-runs";
+// Path: /platform/evo-integrations/test-runs/{run_id}/steps/{step_id}
+export const TEST_RUN_STEPS_COLLECTION = "steps";
+
+// ======================================================
+// Suítes
+// ======================================================
+
+/**
+ * O agrupamento é derivado da DEPENDÊNCIA REAL DE ESTADO, não de estética:
+ * o `external_id` devolvido pelo create alimenta get/update/confirm/revert/cancel,
+ * e o do patient.create alimenta o round-trip e o delete.
+ */
+export type TestSuiteId =
+  | "reading" // S1 — dicionários e leitura; independentes, zero efeito colateral
+  | "appointment" // S2 — ciclo de vida; ordem estrita
+  | "sync" // S3 — depende do cancel da S2
+  | "patient" // S4 — ordem estrita; opcional
+  | "cleanup"; // Z  — limpeza; selecionável (D11)
+
+export interface ITestSuiteMeta {
+  id: TestSuiteId;
+  label: string;
+  /** Ordem estrita = o passo N depende do estado produzido pelo N-1. */
+  ordered: boolean;
+  description: string;
+}
+
+export const TEST_SUITES: readonly ITestSuiteMeta[] = [
+  {
+    id: "reading",
+    label: "Dicionários e leitura",
+    ordered: false,
+    description:
+      "Capabilities de consulta. Nenhuma escreve — pode rodar sozinha com efeito colateral zero.",
+  },
+  {
+    id: "appointment",
+    label: "Ciclo de vida do agendamento",
+    ordered: true,
+    description:
+      "create → get → update → confirm → revert_confirm → cancel. Cada passo depende do external_id do create.",
+  },
+  {
+    id: "sync",
+    label: "Sync não ressuscita",
+    ordered: true,
+    description:
+      "Força o sync de 1 dia e confere que o agendamento cancelado NÃO volta. Exige o cancel da suíte anterior.",
+  },
+  {
+    id: "patient",
+    label: "Paciente",
+    ordered: true,
+    description:
+      "create → round-trip (get+update) → delete. O create nunca foi exercitado por nenhuma rodada do script.",
+  },
+  {
+    id: "cleanup",
+    label: "Varredura de resíduo",
+    ordered: false,
+    description:
+      "Lê a agenda EXTERNA e cancela o que tiver o marcador. Selecionável — quem roda é o dev de integrações, que responde pelo que escolhe.",
+  },
+] as const;
+
+// ======================================================
+// Passos
+// ======================================================
+
+export type TestStepId =
+  // S1
+  | "caps.list"
+  | "ui.config"
+  | "procedure.list"
+  | "status.list"
+  | "dicts.extra"
+  | "patient.list"
+  | "patient.get"
+  | "appointment.list"
+  // S2
+  | "appointment.create"
+  | "appointment.get"
+  | "appointment.update"
+  | "appointment.confirm"
+  | "appointment.revert_confirm"
+  | "appointment.cancel"
+  // S3
+  | "sync.force"
+  // S4
+  | "patient.create"
+  | "patient.roundtrip"
+  | "patient.delete"
+  // Z
+  | "residue.sweep";
+
+export interface ITestStepMeta {
+  id: TestStepId;
+  suite: TestSuiteId;
+  label: string;
+  /**
+   * `true` = o passo ESCREVE no PMS de produção.
+   *
+   * Usado em dois lugares: para o modo somente-leitura e para classificar o custo
+   * de REPETIR um passo — repetir leitura é livre, repetir escrita duplica efeito.
+   */
+  writes: boolean;
+  /** Passos que precisam ter passado antes. Vazio = pode rodar sozinho. */
+  dependsOn: readonly TestStepId[];
+  /** Capability invocada, quando houver. Nem todo passo tem uma. */
+  capability?: string;
+}
+
+/**
+ * Ordem do array = ordem de execução. Não é 1:1 com capability:
+ *   · `residue.sweep` não invoca capability nenhuma (varre a agenda externa);
+ *   · `sync.force` chama `integrations_sync_monitor`, não uma capability;
+ *   · `appointment.list` aparece em dois passos (leitura e varredura);
+ *   · `patient.roundtrip` combina `patient.get` + `patient.update`.
+ */
+export const TEST_STEPS: readonly ITestStepMeta[] = [
+  // ── S1 — leitura ────────────────────────────────────────────────────────────
+  { id: "caps.list", suite: "reading", label: "capabilities", writes: false, dependsOn: [] },
+  { id: "ui.config", suite: "reading", label: "ui-config", writes: false, dependsOn: [] },
+  { id: "procedure.list", suite: "reading", label: "procedure.list", writes: false, dependsOn: [], capability: "appointment.procedure.list" },
+  { id: "status.list", suite: "reading", label: "status.list", writes: false, dependsOn: [], capability: "appointment.status.list" },
+  { id: "dicts.extra", suite: "reading", label: "dicionários extra", writes: false, dependsOn: [] },
+  { id: "patient.list", suite: "reading", label: "patient.list", writes: false, dependsOn: [], capability: "patient.list" },
+  { id: "patient.get", suite: "reading", label: "patient.get", writes: false, dependsOn: [], capability: "patient.get" },
+  { id: "appointment.list", suite: "reading", label: "appointment.list", writes: false, dependsOn: [], capability: "appointment.list" },
+
+  // ── S2 — ciclo de vida ──────────────────────────────────────────────────────
+  { id: "appointment.create", suite: "appointment", label: "create", writes: true, dependsOn: [], capability: "appointment.create" },
+  { id: "appointment.get", suite: "appointment", label: "get", writes: false, dependsOn: ["appointment.create"], capability: "appointment.get" },
+  { id: "appointment.update", suite: "appointment", label: "update", writes: true, dependsOn: ["appointment.create"], capability: "appointment.update" },
+  { id: "appointment.confirm", suite: "appointment", label: "confirm", writes: true, dependsOn: ["appointment.create"], capability: "appointment.confirm" },
+  { id: "appointment.revert_confirm", suite: "appointment", label: "revert_confirm", writes: true, dependsOn: ["appointment.confirm"], capability: "appointment.revert_confirm" },
+  { id: "appointment.cancel", suite: "appointment", label: "cancel", writes: true, dependsOn: ["appointment.create"], capability: "appointment.cancel" },
+
+  // ── S3 — sync ───────────────────────────────────────────────────────────────
+  { id: "sync.force", suite: "sync", label: "sync (1 dia)", writes: true, dependsOn: ["appointment.cancel"] },
+
+  // ── S4 — paciente ───────────────────────────────────────────────────────────
+  { id: "patient.create", suite: "patient", label: "patient.create", writes: true, dependsOn: [], capability: "patient.create" },
+  { id: "patient.roundtrip", suite: "patient", label: "round-trip (get+update)", writes: true, dependsOn: [], capability: "patient.update" },
+  { id: "patient.delete", suite: "patient", label: "patient.delete", writes: true, dependsOn: ["patient.create"], capability: "patient.delete" },
+
+  // ── Z — limpeza ─────────────────────────────────────────────────────────────
+  { id: "residue.sweep", suite: "cleanup", label: "varredura de resíduo", writes: true, dependsOn: [] },
+] as const;
+
+/**
+ * Suíte padrão (D10) — a LINHA DE BASE COMPARÁVEL: todos os passos.
+ *
+ * Só uma corrida com exatamente esta seleção é comparável com a anterior. Sem isso
+ * o output principal da ferramenta ("nenhum defeito novo") seria infalsificável:
+ * bastaria desmarcar o passo que falha.
+ *
+ * Atenção: a seleção não basta. `comparable` também exige `target.create_patient`
+ * ligado — senão `patient.create`/`patient.delete` são pulados e a cobertura real
+ * fica menor que a nominal. Quem decide isso é o backend, em `computeComparable`.
+ */
+export const STANDARD_SUITE_STEP_IDS: readonly TestStepId[] = TEST_STEPS.map(
+  (s) => s.id,
+);
+
+export const READ_ONLY_STEP_IDS: readonly TestStepId[] = TEST_STEPS.filter(
+  (s) => !s.writes,
+).map((s) => s.id);
+
+// ======================================================
+// Checks
+// ======================================================
+
+export type TestCheckStatus = "pass" | "fail" | "skipped";
+
+export interface ITestCheck {
+  /**
+   * Id ESTÁVEL no formato `<step_id>:<slug>` — ex. `appointment.update:sem_divergencia`.
+   *
+   * É a chave que o catálogo de conhecidos referencia. O script antigo casava por
+   * REGEX no texto do label, o que quebrava nos dois sentidos: mudar a redação
+   * descatalogava um defeito em silêncio, e um regex largo engolia defeito novo de
+   * outra causa. Por isso o id vem antes do texto — o label pode ser reescrito à
+   * vontade.
+   */
+  id: string;
+  label: string;
+  status: TestCheckStatus;
+  detail?: string;
+}
+
+// ======================================================
+// Passo executado
+// ======================================================
+
+export type TestStepStatus =
+  | "pending"
+  | "running"
+  | "pass"
+  | "known" // falhou, mas casa com defeito catalogado — não reprova a corrida
+  | "fail" // defeito NOVO
+  | "skipped"
+  | "error";
+
+export interface ITestSchemaValidation {
+  ok: boolean;
+  errors?: Array<{ path: (string | number)[]; message: string; code?: string }>;
+}
+
+/**
+ * O wire — o que o BACKEND mandou para o n8n, lido de
+ * `integrations_sync_monitor GET /calls?run_id=`.
+ *
+ * É a camada que interessa a quem mantém os workflows: a resposta da action mostra
+ * o que a UI mandou, não o que saiu na linha. `DocumentReference` vivo no payload
+ * (a classe de bug que derrubou produção no revert_confirm) só aparece aqui.
+ */
+export interface ITestStepWire {
+  request_json?: string;
+  response_json?: string;
+  n8n_execution_id?: string | null;
+  n8n_workflow_id?: string | null;
+  workflow_url?: string;
+  http_status?: number | null;
+  timed_out?: boolean | null;
+  error_message?: string | null;
+  request_truncated?: boolean | null;
+  response_truncated?: boolean | null;
+}
+
+export interface ITestRunStep extends IFireDoc {
+  step_id: TestStepId;
+  suite: TestSuiteId;
+  order: number;
+  status: TestStepStatus;
+  started_at?: unknown;
+  finished_at?: unknown;
+  duration_ms?: number;
+
+  /** Camada 1 — o que a UI mandou para `integrations_actions` e o que voltou. */
+  layer1?: { request?: unknown; response?: unknown };
+
+  /** Correlação com o wire: `transport_metadata.run_id` da resposta da action. */
+  n8n_run_id?: string | null;
+
+  /** Camada 2 — o que o BE mandou para o n8n. */
+  wire?: ITestStepWire | null;
+
+  schema_validation?: {
+    request?: ITestSchemaValidation;
+    response?: ITestSchemaValidation;
+  } | null;
+
+  checks: ITestCheck[];
+
+  /** Preenchido quando `status === 'known'`: qual defeito catalogado casou. */
+  known_defects?: Array<{ check_id: string; description: string; ref: string }>;
+
+  error?: string | null;
+}
+
+// ======================================================
+// Corrida
+// ======================================================
+
+export type TestRunStatus = "running" | "finished" | "abandoned";
+
+/** Dados do paciente novo, quando o usuário liga a criação (D3). */
+export interface ITestNewPatient {
+  first_name: string;
+  last_name?: string;
+  mobile_phone?: string;
+  email?: string;
+  social_id?: string;
+  birth_date?: string;
+}
+
+export interface ITestRunTarget {
+  /** Paciente de teste JÁ EXISTENTE, usado na leitura e no agendamento. */
+  patient_id: string;
+  /** Só quando `create_patient` está ligado. */
+  new_patient?: ITestNewPatient | null;
+  create_patient: boolean;
+  /** `YYYY-MM-DD`. Recomendado no passado — é aviso, não trava (D2). */
+  slot_date: string;
+  /** `HH:MM`. */
+  slot_time: string;
+  /** Dia povoado para o `appointment.list`; sem isso usa `slot_date`. */
+  list_date?: string | null;
+}
+
+/**
+ * Diagnóstico de segurança — AVISO, não trava (D2).
+ *
+ * Os dois avisos têm gravidade diferente e a UI precisa refletir isso: data futura
+ * só ativa as varreduras D-2/D-0, que dependem de janela; gatilho de evento ligado
+ * dispara na hora do create.
+ */
+export interface ITestRunPreflight {
+  slot_in_past: boolean;
+  /** Quais dos gatilhos de evento estão ligados na agenda-alvo. */
+  triggers_enabled: string[];
+  /**
+   * `notification_config.configs` vazio.
+   *
+   * Distinguir de "desligado" importa: nada dispara nos dois casos, mas aqui é por
+   * AUSÊNCIA DE CONFIGURAÇÃO, não por decisão de alguém.
+   */
+  notification_config_empty: boolean;
+  evaluated_at?: unknown;
+}
+
+/** O que a corrida criou no PMS — permite enumerar resíduo quando o `Z` é desmarcado (D11). */
+export interface ITestRunInventory {
+  appointment_external_ids: string[];
+  patient_external_id?: string | null;
+}
+
+export interface ITestRunVerdict {
+  ok: number;
+  known: number;
+  new_defects: number;
+}
+
+export interface ITestRun extends IFireDoc {
+  adapter_id: string;
+  tenant: string;
+  calendar_id: string;
+
+  target: ITestRunTarget;
+
+  selection: {
+    preset: "standard" | "read-only" | "custom";
+    step_ids: TestStepId[];
+  };
+
+  /** Quantos passos da suíte padrão esta corrida cobriu. */
+  coverage: { ran: number; total: number };
+  /** `true` só quando a seleção é exatamente a suíte padrão (D10). */
+  comparable: boolean;
+
+  preflight: ITestRunPreflight;
+  inventory: ITestRunInventory;
+  verdict: ITestRunVerdict;
+
+  status: TestRunStatus;
+
+  /**
+   * Dono da corrida. Quem orquestra é o FE, então duas abas conduzindo a mesma
+   * corrida escreveriam na mesma agenda de produção em paralelo — outro usuário
+   * abre em modo leitura até assumir explicitamente.
+   */
+  created_by: string;
+  finished_at?: unknown;
+}

package/dist/types/nex-customers/index.d.ts

@@ -1,10 +1,36 @@
 import type { IFireGlobalDoc } from '../shared';
 export type NexCustomerDocumentType = 'cpf' | 'cnpj';
 export type NexCustomerStatus = 'active' | 'inactive';
+/**
+ * feat-125 — papel de um lead do tenant `hub-medica` em relação a um cliente do
+ * Nexus. Enum tipado (e não dicionário) por decisão do time: papel novo é
+ * raríssimo, e a tipagem forte vale mais que evitar um release.
+ */
+export declare const NexCustomerLeadRoleEnum: {
+    readonly Financial: "financial";
+    readonly Administrative: "administrative";
+    readonly Doctor: "doctor";
+};
+export type NexCustomerLeadRole = (typeof NexCustomerLeadRoleEnum)[keyof typeof NexCustomerLeadRoleEnum];
 export interface INexCustomerTenantRef {
     tenant: string;
     display_name?: string | null;
 }
+/**
+ * feat-125 — vínculo com um lead do CRM do `hub-medica`, com o papel que aquele
+ * lead cumpre para este cliente.
+ *
+ * NÃO confundir com `tenant_refs`, que é outro eixo: lá é "o tenant que este
+ * cliente OPERA" (a instância dele na plataforma); aqui é "quem fala com este
+ * cliente pela Hub Médica".
+ *
+ * A chave de unicidade é o PAR (lead_id, role): o mesmo lead pode ser contato
+ * financeiro e administrativo do mesmo cliente.
+ */
+export interface INexCustomerLeadRef {
+    lead_id: string;
+    role: NexCustomerLeadRole;
+}
 export interface INexCustomerAddress {
     zip?: string | null;
     street?: string | null;
@@ -31,5 +57,16 @@ export interface INexCustomer extends IFireGlobalDoc {
     payer_aliases?: string[];
     address?: INexCustomerAddress | null;
     fiscal_data?: INexCustomerFiscalData | null;
+    /**
+     * feat-125 — leads do `hub-medica` que representam este cliente, por papel.
+     * Lado AUTORITATIVO do vínculo: é o que o envio de notificação consulta para
+     * anexar o `crm_lead` e cair na thread do hub-omni.
+     *
+     * NUNCA consultar com `array-contains`: o operador exige igualdade do objeto
+     * inteiro, então a query quebra em silêncio assim que a entrada ganhar um campo
+     * — foi o que travou reusar `tenant_refs` para isto. A busca reversa se faz pelo
+     * lado do lead, via `externalLinkKeys array-contains 'nex_customer:{id}'`.
+     */
+    hm_leads?: INexCustomerLeadRef[];
     notes?: string | null;
 }

package/dist/types/nex-customers/index.js

@@ -1,2 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NexCustomerLeadRoleEnum = void 0;
+/**
+ * feat-125 — papel de um lead do tenant `hub-medica` em relação a um cliente do
+ * Nexus. Enum tipado (e não dicionário) por decisão do time: papel novo é
+ * raríssimo, e a tipagem forte vale mais que evitar um release.
+ */
+exports.NexCustomerLeadRoleEnum = {
+    Financial: 'financial',
+    Administrative: 'administrative',
+    Doctor: 'doctor',
+};

package/dist/types/nex-customers/index.ts

@@ -5,6 +5,20 @@ import type { IFireGlobalDoc } from '../shared';
 export type NexCustomerDocumentType = 'cpf' | 'cnpj';
 export type NexCustomerStatus = 'active' | 'inactive';
 
+/**
+ * feat-125 — papel de um lead do tenant `hub-medica` em relação a um cliente do
+ * Nexus. Enum tipado (e não dicionário) por decisão do time: papel novo é
+ * raríssimo, e a tipagem forte vale mais que evitar um release.
+ */
+export const NexCustomerLeadRoleEnum = {
+  Financial: 'financial',
+  Administrative: 'administrative',
+  Doctor: 'doctor',
+} as const;
+
+export type NexCustomerLeadRole =
+  (typeof NexCustomerLeadRoleEnum)[keyof typeof NexCustomerLeadRoleEnum];
+
 // ── Sub-interfaces ──
 
 export interface INexCustomerTenantRef {
@@ -12,6 +26,22 @@ export interface INexCustomerTenantRef {
   display_name?: string | null;
 }
 
+/**
+ * feat-125 — vínculo com um lead do CRM do `hub-medica`, com o papel que aquele
+ * lead cumpre para este cliente.
+ *
+ * NÃO confundir com `tenant_refs`, que é outro eixo: lá é "o tenant que este
+ * cliente OPERA" (a instância dele na plataforma); aqui é "quem fala com este
+ * cliente pela Hub Médica".
+ *
+ * A chave de unicidade é o PAR (lead_id, role): o mesmo lead pode ser contato
+ * financeiro e administrativo do mesmo cliente.
+ */
+export interface INexCustomerLeadRef {
+  lead_id: string;
+  role: NexCustomerLeadRole;
+}
+
 export interface INexCustomerAddress {
   zip?: string | null;
   street?: string | null;
@@ -58,6 +88,18 @@ export interface INexCustomer extends IFireGlobalDoc {
   // Fiscal data (PJ)
   fiscal_data?: INexCustomerFiscalData | null;
 
+  /**
+   * feat-125 — leads do `hub-medica` que representam este cliente, por papel.
+   * Lado AUTORITATIVO do vínculo: é o que o envio de notificação consulta para
+   * anexar o `crm_lead` e cair na thread do hub-omni.
+   *
+   * NUNCA consultar com `array-contains`: o operador exige igualdade do objeto
+   * inteiro, então a query quebra em silêncio assim que a entrada ganhar um campo
+   * — foi o que travou reusar `tenant_refs` para isto. A busca reversa se faz pelo
+   * lado do lead, via `externalLinkKeys array-contains 'nex_customer:{id}'`.
+   */
+  hm_leads?: INexCustomerLeadRef[];
+
   // Notes
   notes?: string | null;
 }

package/dist/types/shared/external-links.d.ts

@@ -19,10 +19,35 @@ export declare const ExternalObjectTypeEnum: {
     readonly NexCustomer: "nex_customer";
 };
 export type ExternalObjectType = (typeof ExternalObjectTypeEnum)[keyof typeof ExternalObjectTypeEnum];
+/**
+ * feat-125 — sistema DONO do objeto vinculado, quando ele não vive no tenant.
+ *
+ * Existe porque o vínculo passou a atravessar a fronteira da plataforma: o lead do
+ * `hub-medica` aponta para um cliente do Nexus, que é doc de `core/nexus` e não do
+ * tenant. Sem essa marca, quem lê um `externalLink` não tem como saber que não
+ * adianta procurar o objeto no próprio tenant.
+ */
+export declare const ExternalOwnerSystemEnum: {
+    readonly Nexus: "nexus";
+};
+export type ExternalOwnerSystem = (typeof ExternalOwnerSystemEnum)[keyof typeof ExternalOwnerSystemEnum];
 export interface IExternalLink {
     type: ExternalObjectType;
     id: string;
     label?: string;
     ref?: FirestoreDocumentReference;
+    /**
+     * feat-125 — sistema dono do objeto quando ele NÃO vive no tenant.
+     *
+     * **Ausente = objeto do próprio tenant**, que é o caso de todo vínculo existente
+     * até aqui (lead↔paciente, task, invoice, payment-link). Por isso o campo é
+     * opcional e nada precisa ser migrado.
+     *
+     * Consumidores de UI tratam tipo desconhecido por allowlist com fallback (chip
+     * não-navegável), então um link externo já degrada bem sem ler este campo — ele
+     * serve para quem quiser distinguir "não conheço este tipo" de "este objeto é de
+     * outro sistema".
+     */
+    owner?: ExternalOwnerSystem;
     [key: string]: unknown;
 }

package/dist/types/shared/external-links.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ExternalObjectTypeEnum = void 0;
+exports.ExternalOwnerSystemEnum = exports.ExternalObjectTypeEnum = void 0;
 // ----- External object links (for unified UI views across modules)
 // Promoted from evo-task to shared for reuse in invoices, tasks, and other modules
 exports.ExternalObjectTypeEnum = {
@@ -22,3 +22,14 @@ exports.ExternalObjectTypeEnum = {
     NexContract: "nex_contract",
     NexCustomer: "nex_customer",
 };
+/**
+ * feat-125 — sistema DONO do objeto vinculado, quando ele não vive no tenant.
+ *
+ * Existe porque o vínculo passou a atravessar a fronteira da plataforma: o lead do
+ * `hub-medica` aponta para um cliente do Nexus, que é doc de `core/nexus` e não do
+ * tenant. Sem essa marca, quem lê um `externalLink` não tem como saber que não
+ * adianta procurar o objeto no próprio tenant.
+ */
+exports.ExternalOwnerSystemEnum = {
+    Nexus: "nexus",
+};

package/dist/types/shared/external-links.ts

@@ -26,10 +26,38 @@ export const ExternalObjectTypeEnum = {
 export type ExternalObjectType =
   (typeof ExternalObjectTypeEnum)[keyof typeof ExternalObjectTypeEnum];
 
+/**
+ * feat-125 — sistema DONO do objeto vinculado, quando ele não vive no tenant.
+ *
+ * Existe porque o vínculo passou a atravessar a fronteira da plataforma: o lead do
+ * `hub-medica` aponta para um cliente do Nexus, que é doc de `core/nexus` e não do
+ * tenant. Sem essa marca, quem lê um `externalLink` não tem como saber que não
+ * adianta procurar o objeto no próprio tenant.
+ */
+export const ExternalOwnerSystemEnum = {
+  Nexus: "nexus",
+} as const;
+
+export type ExternalOwnerSystem =
+  (typeof ExternalOwnerSystemEnum)[keyof typeof ExternalOwnerSystemEnum];
+
 export interface IExternalLink {
   type: ExternalObjectType;
   id: string;
   label?: string;
   ref?: FirestoreDocumentReference;
+  /**
+   * feat-125 — sistema dono do objeto quando ele NÃO vive no tenant.
+   *
+   * **Ausente = objeto do próprio tenant**, que é o caso de todo vínculo existente
+   * até aqui (lead↔paciente, task, invoice, payment-link). Por isso o campo é
+   * opcional e nada precisa ser migrado.
+   *
+   * Consumidores de UI tratam tipo desconhecido por allowlist com fallback (chip
+   * não-navegável), então um link externo já degrada bem sem ler este campo — ele
+   * serve para quem quiser distinguir "não conheço este tipo" de "este objeto é de
+   * outro sistema".
+   */
+  owner?: ExternalOwnerSystem;
   [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.505",
+  "version": "1.3.510",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",