evo360-types 1.3.656 → 1.3.662

package/dist/types/evo-modules/index.d.ts

@@ -0,0 +1,227 @@
+import type { IFireDoc, IFireGlobalDoc } from "../shared";
+import type { ITenantModuleEntitlement, TenantModuleSource, TenantModuleStatus } from "../evo-tenant";
+import type { EntitlementAuditAction, IEntitlementAuditActor } from "../evo-telemedicine";
+export * from "./catalog";
+export * from "./activation";
+export declare const EVO_MODULES_APP = "evo-modules";
+export declare const MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+export declare const MODULES_PROVISIONING_COLLECTION = "provisioning";
+export declare const MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+export declare const MODULES_LOCK_TTL_MS: number;
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+export declare const MODULE_KEY_PATTERN: RegExp;
+export type ModuleAction = "enable" | "disable" | "trial" | "override";
+export declare const ModuleActionEnum: {
+    readonly Enable: "enable";
+    readonly Disable: "disable";
+    readonly Trial: "trial";
+    readonly Override: "override";
+};
+export type ModuleStepKind = "entitlement" | "rbac_group" | "rbac_recompute" | "contract_allowance" | "contract_check" | "rollout_check";
+export declare const ModuleStepKindEnum: {
+    readonly Entitlement: "entitlement";
+    readonly RbacGroup: "rbac_group";
+    readonly RbacRecompute: "rbac_recompute";
+    readonly ContractAllowance: "contract_allowance";
+    readonly ContractCheck: "contract_check";
+    readonly RolloutCheck: "rollout_check";
+};
+export declare const MODULE_STEP_KINDS: readonly ModuleStepKind[];
+export interface IModuleRolloutDescriptor {
+    /** Path completo do doc (4 segmentos: `platform/<app>/<col>/<doc>`). */
+    path: string;
+    /**
+     * `flags_map`: doc genérico `{ flags: { [flag]: boolean }, emergency_kill }`.
+     * `legacy_fields`: doc com um campo booleano por flag (telemedicina).
+     */
+    layout: "flags_map" | "legacy_fields";
+    /** flag -> campo do doc (`legacy_fields`) ou chave em `flags` (`flags_map`). */
+    flags: Record<string, string>;
+}
+export interface IModuleCapabilityDefinition {
+    label: string;
+    default: boolean | number | string;
+}
+export interface IModuleAllowanceMetric {
+    /** Chave de `NexFinopsMetricCatalog`. */
+    metric: string;
+    /** Gravado no contrato vigente quando a chave está ausente (Q6). */
+    default_included: number;
+}
+export interface IPlatformModuleDefinition {
+    /** `MODULE_KEY_PATTERN`; é a chave em `tenants/{t}.modules`. */
+    key: string;
+    label: string;
+    description?: string;
+    /** App do Firestore onde vivem os dados do módulo (`evo-telemedicine`, `evo-csq`). */
+    app_id: string;
+    capabilities: Record<string, IModuleCapabilityDefinition>;
+    /** Status/origem gravados no `enable` de um tenant sem entitlement. */
+    default_entitlement: {
+        status: TenantModuleStatus;
+        source: TenantModuleSource;
+    };
+    /** Tenant novo nasce com o módulo (`createTenant`). */
+    default_for_new_tenants: boolean;
+    /** Grupos RBAC globais que tornam os papéis do módulo atribuíveis. */
+    rbac_groups: string[];
+    allowance_metrics: IModuleAllowanceMetric[];
+    rollout: IModuleRolloutDescriptor | null;
+    depends_on: string[];
+    provisioning: {
+        enable: ModuleStepKind[];
+        disable: ModuleStepKind[];
+    };
+    legacy?: {
+        /** Trilhas antigas (relativas a `tenants/{t}/`), lidas pelo histórico e nunca escritas. */
+        audit_collections?: string[];
+    };
+}
+export type ModuleStepStatus = "pending" | "noop" | "change" | "done" | "failed" | "blocked" | "skipped";
+export interface IModuleProvisioningStep {
+    kind: ModuleStepKind;
+    status: ModuleStepStatus;
+    summary: string;
+    before?: unknown;
+    after?: unknown;
+    error?: string | null;
+    started_at?: Date | null;
+    finished_at?: Date | null;
+}
+export type ModuleRunMode = "plan" | "apply";
+export type ModuleRunStatus = "planned" | "running" | "done" | "failed" | "blocked" | "superseded";
+export interface IModuleChangeParams {
+    /** `trial`: obrigatório. */
+    expires_at?: Date | null;
+    /** `override`: obrigatório. */
+    override_until?: Date | null;
+    /** `enable`: libera o passo `contract_allowance` quando ele vem `blocked` (Q6). */
+    allow_without_contract?: boolean;
+    /** `disable`: remove o grupo RBAC se nenhum outro módulo ativo o declara (Q7). */
+    purge_rbac?: boolean;
+    /** `disable`: grava `suspended` em vez de `cancelled`. */
+    suspend?: boolean;
+}
+export interface IModuleRunActor extends IEntitlementAuditActor {
+    login_id?: string;
+}
+export interface IModuleProvisioningRun extends IFireDoc {
+    tenant: string;
+    module: string;
+    action: ModuleAction;
+    mode: ModuleRunMode;
+    status: ModuleRunStatus;
+    params: IModuleChangeParams;
+    /** Hash estável dos passos planejados (kind+status+after). Muda ⇒ `PLAN_DRIFT`. */
+    plan_hash: string;
+    /** `PLATFORM_MODULE_CATALOG_VERSION` de quem planejou/aplicou. */
+    types_version: string;
+    steps: IModuleProvisioningStep[];
+    actor: IModuleRunActor;
+    reason: string;
+    /** Run `apply` que este retoma. */
+    resumed_from?: string | null;
+    /** Run `plan` que originou este `apply`. */
+    plan_run_id?: string | null;
+    error?: string | null;
+    finished_at?: Date | null;
+}
+/** Lock no doc `tenants/{t}/apps/evo-modules`, campo `locks.{module}`. */
+export interface IModuleLock {
+    run_id: string;
+    expires_at: Date;
+}
+export interface IModuleRolloutDoc extends IFireGlobalDoc {
+    flags: Record<string, boolean>;
+    emergency_kill: boolean;
+    updated_at: Date;
+    updated_by: string;
+}
+/** Estado de rollout normalizado (o mesmo para os dois layouts). */
+export interface IModuleRolloutState {
+    module: string;
+    path: string;
+    /** `false` ⇒ doc ausente/ilegível: tudo negado. */
+    exists: boolean;
+    flags: Record<string, boolean>;
+    emergency_kill: boolean;
+    updated_at: Date | null;
+    updated_by: string | null;
+}
+export interface IModuleEntitlementAudit extends IFireDoc {
+    module: string;
+    action: EntitlementAuditAction;
+    before?: ITenantModuleEntitlement | null;
+    after: ITenantModuleEntitlement;
+    actor: IEntitlementAuditActor;
+    reason: string;
+    occurred_at: Date;
+    correlation_id?: string;
+    run_id?: string;
+}
+export interface IModuleStepContext {
+    tenant: string;
+    module: IPlatformModuleDefinition;
+    action: ModuleAction;
+    params: IModuleChangeParams;
+    actor_user_id: string | null;
+    /** Passos anteriores do mesmo run (estado corrente). */
+    previous_steps?: IModuleProvisioningStep[];
+}
+export type ModuleStepPlanResult = Pick<IModuleProvisioningStep, "status" | "summary" | "before" | "after">;
+export type ModuleStepApplyResult = Pick<IModuleProvisioningStep, "status" | "summary" | "after">;
+export interface IModuleStepExecutor {
+    plan(ctx: IModuleStepContext): Promise<ModuleStepPlanResult>;
+    apply(ctx: IModuleStepContext): Promise<ModuleStepApplyResult>;
+}
+export interface IModuleChangeRequest {
+    tenant: string;
+    module: string;
+    action: ModuleAction;
+    params?: IModuleChangeParams;
+    reason: string;
+}
+export interface IModuleApplyRequest {
+    tenant: string;
+    /** Aplica o plano deste run (`mode: 'plan'`). Exclusivo com `resume_run_id`. */
+    plan_run_id?: string;
+    /** Retoma um run `apply` em `failed`/`blocked`. */
+    resume_run_id?: string;
+    /** Sobrepõe params do plano (só `allow_without_contract` faz sentido aqui). */
+    params?: Pick<IModuleChangeParams, "allow_without_contract">;
+}
+export interface IModuleOverviewRequest {
+    tenant: string;
+}
+export interface IModuleOverviewEntry {
+    definition: IPlatformModuleDefinition;
+    entitlement: ITenantModuleEntitlement | null;
+    active: boolean;
+    rollout: IModuleRolloutState | null;
+}
+export interface IModuleOverviewResponse {
+    ok: true;
+    tenant: string;
+    catalog_version: string;
+    modules: IModuleOverviewEntry[];
+    /** Últimos 10 runs (plan e apply), mais recentes primeiro. */
+    runs: IModuleProvisioningRun[];
+    /** Últimas 30 entradas de auditoria (caminho genérico + legados), por `occurred_at` desc. */
+    audit: IModuleEntitlementAudit[];
+}
+export interface IModulePlanResponse {
+    ok: true;
+    run: IModuleProvisioningRun;
+}
+export type ModuleApplyErrorCode = "PLAN_DRIFT" | "MODULE_LOCKED" | "RUN_NOT_FOUND" | "RUN_NOT_RESUMABLE";
+export type IModuleApplyResponse = {
+    ok: true;
+    run: IModuleProvisioningRun;
+}
+/** O estado mudou desde o plano: `plan` é o run novo (`mode: 'plan'`) para revisar. */
+ | {
+    ok: false;
+    error: "PLAN_DRIFT";
+    plan: IModuleProvisioningRun;
+};

package/dist/types/evo-modules/index.js

@@ -0,0 +1,75 @@
+"use strict";
+// ======================================================
+// evo-modules (feat-263 — Módulos da plataforma)
+//
+// Entitlement de módulos por tenant: "este cliente tem direito ao módulo X?".
+// NÃO é feature flag: o kill switch operacional de cada módulo é o `rollout`
+// (doc de plataforma), um gate independente.
+//
+// Storage do estado continua em `tenants/{t}.modules[key]`
+// (`ITenantModuleEntitlement`, feat-160 D5). Este namespace acrescenta:
+// - o catálogo em código (`PLATFORM_MODULE_CATALOG`), que carrega
+//   comportamento (passos de provisionamento, grupos RBAC, métricas de franquia);
+// - a decisão única `isModuleActive` / `hasModuleCapability`, usada por
+//   backend, web-app e Nexus (o Flutter espelha pela fixture de paridade);
+// - os tipos do run de provisionamento, do doc de rollout genérico e da
+//   auditoria genérica.
+//
+// Firestore (por tenant):
+// - App doc (locks):     /tenants/{t}/apps/evo-modules                       campo `locks.{module}`
+// - Auditoria:           /tenants/{t}/apps/evo-modules/entitlement-audit/{id}
+// - Provisionamento:     /tenants/{t}/apps/evo-modules/provisioning/{runId}
+//
+// Plataforma (só backend):
+// - Rollout genérico:    /platform/evo-modules/rollout/{module}
+//   (a telemedicina continua em `platform/evo-telemedicine/config/rollout`,
+//   lida pelo mesmo reader via `rollout.layout = 'legacy_fields'`).
+// ======================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_STEP_KINDS = exports.ModuleStepKindEnum = exports.ModuleActionEnum = exports.MODULE_KEY_PATTERN = exports.MODULES_LOCK_TTL_MS = exports.MODULES_ROLLOUT_PLATFORM_PATH = exports.MODULES_PROVISIONING_COLLECTION = exports.MODULES_ENTITLEMENT_AUDIT_COLLECTION = exports.EVO_MODULES_APP = void 0;
+__exportStar(require("./catalog"), exports);
+__exportStar(require("./activation"), exports);
+exports.EVO_MODULES_APP = "evo-modules";
+exports.MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+exports.MODULES_PROVISIONING_COLLECTION = "provisioning";
+exports.MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+exports.MODULES_LOCK_TTL_MS = 10 * 60 * 1000;
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+exports.MODULE_KEY_PATTERN = /^[a-z][a-z0-9_]{1,40}$/;
+exports.ModuleActionEnum = {
+    Enable: "enable",
+    Disable: "disable",
+    Trial: "trial",
+    Override: "override",
+};
+exports.ModuleStepKindEnum = {
+    Entitlement: "entitlement",
+    RbacGroup: "rbac_group",
+    RbacRecompute: "rbac_recompute",
+    ContractAllowance: "contract_allowance",
+    ContractCheck: "contract_check",
+    RolloutCheck: "rollout_check",
+};
+exports.MODULE_STEP_KINDS = [
+    "entitlement",
+    "rbac_group",
+    "rbac_recompute",
+    "contract_allowance",
+    "contract_check",
+    "rollout_check",
+];

package/dist/types/evo-modules/index.ts

@@ -0,0 +1,329 @@
+// ======================================================
+// evo-modules (feat-263 — Módulos da plataforma)
+//
+// Entitlement de módulos por tenant: "este cliente tem direito ao módulo X?".
+// NÃO é feature flag: o kill switch operacional de cada módulo é o `rollout`
+// (doc de plataforma), um gate independente.
+//
+// Storage do estado continua em `tenants/{t}.modules[key]`
+// (`ITenantModuleEntitlement`, feat-160 D5). Este namespace acrescenta:
+// - o catálogo em código (`PLATFORM_MODULE_CATALOG`), que carrega
+//   comportamento (passos de provisionamento, grupos RBAC, métricas de franquia);
+// - a decisão única `isModuleActive` / `hasModuleCapability`, usada por
+//   backend, web-app e Nexus (o Flutter espelha pela fixture de paridade);
+// - os tipos do run de provisionamento, do doc de rollout genérico e da
+//   auditoria genérica.
+//
+// Firestore (por tenant):
+// - App doc (locks):     /tenants/{t}/apps/evo-modules                       campo `locks.{module}`
+// - Auditoria:           /tenants/{t}/apps/evo-modules/entitlement-audit/{id}
+// - Provisionamento:     /tenants/{t}/apps/evo-modules/provisioning/{runId}
+//
+// Plataforma (só backend):
+// - Rollout genérico:    /platform/evo-modules/rollout/{module}
+//   (a telemedicina continua em `platform/evo-telemedicine/config/rollout`,
+//   lida pelo mesmo reader via `rollout.layout = 'legacy_fields'`).
+// ======================================================
+
+import type { IFireDoc, IFireGlobalDoc } from "../shared";
+import type {
+  ITenantModuleEntitlement,
+  TenantModuleSource,
+  TenantModuleStatus,
+} from "../evo-tenant";
+import type {
+  EntitlementAuditAction,
+  IEntitlementAuditActor,
+} from "../evo-telemedicine";
+
+export * from "./catalog";
+export * from "./activation";
+
+export const EVO_MODULES_APP = "evo-modules";
+export const MODULES_ENTITLEMENT_AUDIT_COLLECTION = "entitlement-audit";
+export const MODULES_PROVISIONING_COLLECTION = "provisioning";
+export const MODULES_ROLLOUT_PLATFORM_PATH = "platform/evo-modules/rollout";
+/** TTL do lock por tenant+módulo durante um apply. */
+export const MODULES_LOCK_TTL_MS = 10 * 60 * 1000;
+
+/** Regex da chave de módulo (`tenants/{t}.modules[key]`). */
+export const MODULE_KEY_PATTERN = /^[a-z][a-z0-9_]{1,40}$/;
+
+export type ModuleAction = "enable" | "disable" | "trial" | "override";
+export const ModuleActionEnum = {
+  Enable: "enable",
+  Disable: "disable",
+  Trial: "trial",
+  Override: "override",
+} as const;
+
+export type ModuleStepKind =
+  | "entitlement"
+  | "rbac_group"
+  | "rbac_recompute"
+  | "contract_allowance"
+  | "contract_check"
+  | "rollout_check";
+export const ModuleStepKindEnum = {
+  Entitlement: "entitlement",
+  RbacGroup: "rbac_group",
+  RbacRecompute: "rbac_recompute",
+  ContractAllowance: "contract_allowance",
+  ContractCheck: "contract_check",
+  RolloutCheck: "rollout_check",
+} as const;
+export const MODULE_STEP_KINDS: readonly ModuleStepKind[] = [
+  "entitlement",
+  "rbac_group",
+  "rbac_recompute",
+  "contract_allowance",
+  "contract_check",
+  "rollout_check",
+];
+
+// ----- Catálogo
+
+export interface IModuleRolloutDescriptor {
+  /** Path completo do doc (4 segmentos: `platform/<app>/<col>/<doc>`). */
+  path: string;
+  /**
+   * `flags_map`: doc genérico `{ flags: { [flag]: boolean }, emergency_kill }`.
+   * `legacy_fields`: doc com um campo booleano por flag (telemedicina).
+   */
+  layout: "flags_map" | "legacy_fields";
+  /** flag -> campo do doc (`legacy_fields`) ou chave em `flags` (`flags_map`). */
+  flags: Record<string, string>;
+}
+
+export interface IModuleCapabilityDefinition {
+  label: string;
+  default: boolean | number | string;
+}
+
+export interface IModuleAllowanceMetric {
+  /** Chave de `NexFinopsMetricCatalog`. */
+  metric: string;
+  /** Gravado no contrato vigente quando a chave está ausente (Q6). */
+  default_included: number;
+}
+
+export interface IPlatformModuleDefinition {
+  /** `MODULE_KEY_PATTERN`; é a chave em `tenants/{t}.modules`. */
+  key: string;
+  label: string;
+  description?: string;
+  /** App do Firestore onde vivem os dados do módulo (`evo-telemedicine`, `evo-csq`). */
+  app_id: string;
+  capabilities: Record<string, IModuleCapabilityDefinition>;
+  /** Status/origem gravados no `enable` de um tenant sem entitlement. */
+  default_entitlement: { status: TenantModuleStatus; source: TenantModuleSource };
+  /** Tenant novo nasce com o módulo (`createTenant`). */
+  default_for_new_tenants: boolean;
+  /** Grupos RBAC globais que tornam os papéis do módulo atribuíveis. */
+  rbac_groups: string[];
+  allowance_metrics: IModuleAllowanceMetric[];
+  rollout: IModuleRolloutDescriptor | null;
+  depends_on: string[];
+  provisioning: { enable: ModuleStepKind[]; disable: ModuleStepKind[] };
+  legacy?: {
+    /** Trilhas antigas (relativas a `tenants/{t}/`), lidas pelo histórico e nunca escritas. */
+    audit_collections?: string[];
+  };
+}
+
+// ----- Run de provisionamento: tenants/{t}/apps/evo-modules/provisioning/{runId}
+
+export type ModuleStepStatus =
+  | "pending"
+  | "noop"
+  | "change"
+  | "done"
+  | "failed"
+  | "blocked"
+  | "skipped";
+
+export interface IModuleProvisioningStep {
+  kind: ModuleStepKind;
+  status: ModuleStepStatus;
+  summary: string;
+  before?: unknown;
+  after?: unknown;
+  error?: string | null;
+  started_at?: Date | null;
+  finished_at?: Date | null;
+}
+
+export type ModuleRunMode = "plan" | "apply";
+export type ModuleRunStatus =
+  | "planned"
+  | "running"
+  | "done"
+  | "failed"
+  | "blocked"
+  | "superseded";
+
+export interface IModuleChangeParams {
+  /** `trial`: obrigatório. */
+  expires_at?: Date | null;
+  /** `override`: obrigatório. */
+  override_until?: Date | null;
+  /** `enable`: libera o passo `contract_allowance` quando ele vem `blocked` (Q6). */
+  allow_without_contract?: boolean;
+  /** `disable`: remove o grupo RBAC se nenhum outro módulo ativo o declara (Q7). */
+  purge_rbac?: boolean;
+  /** `disable`: grava `suspended` em vez de `cancelled`. */
+  suspend?: boolean;
+}
+
+export interface IModuleRunActor extends IEntitlementAuditActor {
+  login_id?: string;
+}
+
+export interface IModuleProvisioningRun extends IFireDoc {
+  tenant: string;
+  module: string;
+  action: ModuleAction;
+  mode: ModuleRunMode;
+  status: ModuleRunStatus;
+  params: IModuleChangeParams;
+  /** Hash estável dos passos planejados (kind+status+after). Muda ⇒ `PLAN_DRIFT`. */
+  plan_hash: string;
+  /** `PLATFORM_MODULE_CATALOG_VERSION` de quem planejou/aplicou. */
+  types_version: string;
+  steps: IModuleProvisioningStep[];
+  actor: IModuleRunActor;
+  reason: string;
+  /** Run `apply` que este retoma. */
+  resumed_from?: string | null;
+  /** Run `plan` que originou este `apply`. */
+  plan_run_id?: string | null;
+  error?: string | null;
+  finished_at?: Date | null;
+}
+
+/** Lock no doc `tenants/{t}/apps/evo-modules`, campo `locks.{module}`. */
+export interface IModuleLock {
+  run_id: string;
+  expires_at: Date;
+}
+
+// ----- Rollout genérico: platform/evo-modules/rollout/{module}
+
+export interface IModuleRolloutDoc extends IFireGlobalDoc {
+  flags: Record<string, boolean>;
+  emergency_kill: boolean;
+  updated_at: Date;
+  updated_by: string;
+}
+
+/** Estado de rollout normalizado (o mesmo para os dois layouts). */
+export interface IModuleRolloutState {
+  module: string;
+  path: string;
+  /** `false` ⇒ doc ausente/ilegível: tudo negado. */
+  exists: boolean;
+  flags: Record<string, boolean>;
+  emergency_kill: boolean;
+  updated_at: Date | null;
+  updated_by: string | null;
+}
+
+// ----- Auditoria genérica: tenants/{t}/apps/evo-modules/entitlement-audit/{id}
+
+export interface IModuleEntitlementAudit extends IFireDoc {
+  module: string;
+  action: EntitlementAuditAction;
+  before?: ITenantModuleEntitlement | null;
+  after: ITenantModuleEntitlement;
+  actor: IEntitlementAuditActor;
+  reason: string;
+  occurred_at: Date;
+  correlation_id?: string;
+  run_id?: string;
+}
+
+// ----- Executor de passo injetável
+//
+// Permite que um passo seja implementado fora do `@evo/model` (ex.: a franquia
+// no `@evo/nex-model`) sem dependência entre os packages: quem roda o runner
+// (functions-nexus, CLI) registra o executor.
+
+export interface IModuleStepContext {
+  tenant: string;
+  module: IPlatformModuleDefinition;
+  action: ModuleAction;
+  params: IModuleChangeParams;
+  actor_user_id: string | null;
+  /** Passos anteriores do mesmo run (estado corrente). */
+  previous_steps?: IModuleProvisioningStep[];
+}
+
+export type ModuleStepPlanResult = Pick<
+  IModuleProvisioningStep,
+  "status" | "summary" | "before" | "after"
+>;
+export type ModuleStepApplyResult = Pick<
+  IModuleProvisioningStep,
+  "status" | "summary" | "after"
+>;
+
+export interface IModuleStepExecutor {
+  plan(ctx: IModuleStepContext): Promise<ModuleStepPlanResult>;
+  apply(ctx: IModuleStepContext): Promise<ModuleStepApplyResult>;
+}
+
+// ----- Callables do Nexus (`nex_tenants-*`)
+//
+// Datas atravessam o callable como ISO string.
+
+export interface IModuleChangeRequest {
+  tenant: string;
+  module: string;
+  action: ModuleAction;
+  params?: IModuleChangeParams;
+  reason: string;
+}
+
+export interface IModuleApplyRequest {
+  tenant: string;
+  /** Aplica o plano deste run (`mode: 'plan'`). Exclusivo com `resume_run_id`. */
+  plan_run_id?: string;
+  /** Retoma um run `apply` em `failed`/`blocked`. */
+  resume_run_id?: string;
+  /** Sobrepõe params do plano (só `allow_without_contract` faz sentido aqui). */
+  params?: Pick<IModuleChangeParams, "allow_without_contract">;
+}
+
+export interface IModuleOverviewRequest {
+  tenant: string;
+}
+
+export interface IModuleOverviewEntry {
+  definition: IPlatformModuleDefinition;
+  entitlement: ITenantModuleEntitlement | null;
+  active: boolean;
+  rollout: IModuleRolloutState | null;
+}
+
+export interface IModuleOverviewResponse {
+  ok: true;
+  tenant: string;
+  catalog_version: string;
+  modules: IModuleOverviewEntry[];
+  /** Últimos 10 runs (plan e apply), mais recentes primeiro. */
+  runs: IModuleProvisioningRun[];
+  /** Últimas 30 entradas de auditoria (caminho genérico + legados), por `occurred_at` desc. */
+  audit: IModuleEntitlementAudit[];
+}
+
+export interface IModulePlanResponse {
+  ok: true;
+  run: IModuleProvisioningRun;
+}
+
+export type ModuleApplyErrorCode = "PLAN_DRIFT" | "MODULE_LOCKED" | "RUN_NOT_FOUND" | "RUN_NOT_RESUMABLE";
+
+export type IModuleApplyResponse =
+  | { ok: true; run: IModuleProvisioningRun }
+  /** O estado mudou desde o plano: `plan` é o run novo (`mode: 'plan'`) para revisar. */
+  | { ok: false; error: "PLAN_DRIFT"; plan: IModuleProvisioningRun };

package/dist/types/evo-task/index.d.ts

@@ -191,6 +191,7 @@ export interface IAutoTask extends ITaskBase {
     retry?: ITaskRetryPolicy;
     on_failure?: ITaskOnFailure;
     runner_state?: ITaskRunnerState;
+    outcome?: ITaskOutcome | null;
     auto: ITaskAutoSpec;
 }
 export type ITask = IHumanTask | IAutoTask;
@@ -198,8 +199,20 @@ export declare const TaskExecutionStatusEnum: {
     readonly Success: "success";
     readonly Error: "error";
     readonly Retry: "retry";
+    readonly Suppressed: "suppressed";
 };
 export type TaskExecutionStatus = (typeof TaskExecutionStatusEnum)[keyof typeof TaskExecutionStatusEnum];
+export type TaskOutcomeClass = "legitimate" | "defect";
+export interface ITaskOutcome {
+    class: TaskOutcomeClass;
+    reason: string;
+    label: string;
+    message: string;
+    action_hint?: string;
+    scope?: string;
+    details?: Record<string, unknown>;
+    at: Date;
+}
 export interface ITaskExecution extends IFireDoc {
     taskId: string;
     handler: TaskAutoHandler;
@@ -214,6 +227,7 @@ export interface ITaskExecution extends IFireDoc {
         code?: string | number;
         details?: Record<string, unknown>;
     };
+    outcome?: ITaskOutcome;
     provider?: {
         name?: string;
         message_id?: string;

package/dist/types/evo-task/index.js

@@ -167,4 +167,7 @@ exports.TaskExecutionStatusEnum = {
     Success: "success",
     Error: "error",
     Retry: "retry",
+    // Handler ran and decided not to deliver; `outcome` says why. The runner
+    // finalizes the task directly (no retry, fallback or handoff).
+    Suppressed: "suppressed",
 };