@baruk/core 0.4.2 → 0.6.0

package/dist/fiscal/sync/lease.js

@@ -0,0 +1,139 @@
+import { uuidv7 } from '@baruk/shared';
+/**
+ * Prazo padrão da vez.
+ *
+ * Dez minutos: mais do que qualquer lote de 50 documentos precisa, e menos do
+ * que o intervalo entre ciclos diários — de modo que um worker morto nunca
+ * atrase o cliente para o dia seguinte. Lotes longos renovam com `heartbeat`.
+ */
+export const DEFAULT_LEASE_TTL_MS = 10 * 60_000;
+/**
+ * Toma a vez. Devolve `null` quando outro processo VIVO a tem.
+ *
+ * `null` não é erro e não merece log de erro: é a resposta correta e frequente
+ * quando dois workers percorrem a mesma carteira.
+ */
+export async function acquireFiscalSyncLease(tx, input) {
+    const now = input.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + (input.ttlMs ?? DEFAULT_LEASE_TTL_MS));
+    const { stream } = input;
+    // A CTE fotografa o titular ANTERIOR. Ela não participa da exclusão — quem
+    // exclui é o `ON CONFLICT` —, serve só para dizer se esta tomada veio de uma
+    // vez devolvida (caminho normal) ou arrancada de um titular vencido (worker
+    // morto). Sob disputa real a segunda transação nem chega aqui: ela bloqueia
+    // na linha e depois reprova no `WHERE`.
+    const rows = await tx `
+    WITH anterior AS (
+      SELECT released_at
+        FROM fiscal_sync_lease
+       WHERE tenant_id = ${input.tenantId} AND client_id = ${stream.clientId}
+         AND source = ${stream.source} AND environment = ${stream.environment}
+         AND document_type = ${stream.documentType}
+    )
+    INSERT INTO fiscal_sync_lease (
+      id, tenant_id, client_id, source, environment, document_type,
+      holder, run_id, acquired_at, heartbeat_at, expires_at, released_at, updated_at
+    ) VALUES (
+      ${uuidv7()}, ${input.tenantId}, ${stream.clientId}, ${stream.source},
+      ${stream.environment}, ${stream.documentType},
+      ${input.holder}, ${input.runId ?? null}, ${now}, ${now}, ${expiresAt}, NULL, now()
+    )
+    ON CONFLICT (tenant_id, client_id, source, environment, document_type)
+    DO UPDATE SET
+      holder          = EXCLUDED.holder,
+      run_id          = EXCLUDED.run_id,
+      acquired_at     = EXCLUDED.acquired_at,
+      heartbeat_at    = EXCLUDED.heartbeat_at,
+      expires_at      = EXCLUDED.expires_at,
+      released_at     = NULL,
+      -- Só conta como RETOMADA quando o titular anterior não devolveu. Uma vez
+      -- livre e devolvida é o caminho normal, e inflá-lo apagaria o sinal de
+      -- que existe um worker morrendo no meio do lote.
+      recovered_count = fiscal_sync_lease.recovered_count
+                        + CASE WHEN fiscal_sync_lease.released_at IS NULL THEN 1 ELSE 0 END,
+      updated_at      = now()
+    WHERE fiscal_sync_lease.released_at IS NOT NULL
+       OR fiscal_sync_lease.expires_at <= ${now}
+    RETURNING id, holder, acquired_at, expires_at, recovered_count,
+              (SELECT released_at IS NULL FROM anterior) AS recovered
+  `;
+    const r = rows[0];
+    if (!r)
+        return null;
+    return {
+        id: r.id,
+        holder: r.holder,
+        acquiredAt: r.acquired_at,
+        expiresAt: r.expires_at,
+        recoveredCount: r.recovered_count,
+        // Sem linha anterior a CTE devolve NULL: é uma vez nova, não uma retomada.
+        recovered: r.recovered === true,
+    };
+}
+/**
+ * Renova o prazo — e confirma que a vez ainda é nossa.
+ *
+ * O `WHERE holder = ...` não é zelo: um lote que demorou mais do que o prazo já
+ * PERDEU a vez para outro worker, e continuar escrevendo depois disso é
+ * exatamente a corrida que o lease existe para impedir. `false` significa
+ * "pare agora", e quem chama tem de obedecer.
+ */
+export async function heartbeatFiscalSyncLease(tx, input) {
+    const now = input.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + (input.ttlMs ?? DEFAULT_LEASE_TTL_MS));
+    const rows = await tx `
+    UPDATE fiscal_sync_lease
+       SET heartbeat_at = ${now}, expires_at = ${expiresAt}, updated_at = now()
+     WHERE id = ${input.leaseId}
+       AND holder = ${input.holder}
+       AND released_at IS NULL
+       AND expires_at > ${now}
+    RETURNING id
+  `;
+    return rows.length > 0;
+}
+/**
+ * Devolve a vez.
+ *
+ * Idempotente e tolerante: devolver uma vez que já foi tomada por outro não é
+ * erro, é o desfecho normal de um worker que demorou demais. Devolve `false`
+ * para que a trilha saiba, sem lançar.
+ */
+export async function releaseFiscalSyncLease(tx, input) {
+    const now = input.now ?? new Date();
+    const rows = await tx `
+    UPDATE fiscal_sync_lease
+       SET released_at = ${now}, updated_at = now()
+     WHERE id = ${input.leaseId} AND holder = ${input.holder} AND released_at IS NULL
+    RETURNING id
+  `;
+    return rows.length > 0;
+}
+/**
+ * As vezes vencidas que ninguém devolveu.
+ *
+ * A retomada não depende desta função — `acquire` já toma o que venceu. Ela
+ * existe para OBSERVAÇÃO: uma lista que nunca esvazia é um worker que morre
+ * sempre no mesmo cliente, e isso é uma pergunta que nenhum contador agregado
+ * responde.
+ */
+export async function listStaleFiscalSyncLeases(tx, now = new Date()) {
+    const rows = await tx `
+    SELECT id, client_id, source, environment, document_type, holder,
+           expires_at, recovered_count
+      FROM fiscal_sync_lease
+     WHERE released_at IS NULL AND expires_at <= ${now}
+     ORDER BY expires_at
+  `;
+    return rows.map((r) => ({
+        id: r.id,
+        clientId: r.client_id,
+        source: r.source,
+        environment: r.environment,
+        documentType: r.document_type,
+        holder: r.holder,
+        expiresAt: r.expires_at,
+        recoveredCount: r.recovered_count,
+    }));
+}
+//# sourceMappingURL=lease.js.map

package/dist/fiscal/sync/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../../src/fiscal/sync/lease.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/sync/observability.d.ts

@@ -0,0 +1,148 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalDocumentType } from '../ingestion/provider.js';
+/**
+ * O que aconteceu, contado a partir do banco — e nunca a partir de estimativa.
+ *
+ * ## Toda métrica aqui é FACTUAL
+ *
+ * Cada número sai de linhas gravadas por execuções que de fato ocorreram. Não há
+ * contador em memória (que zera a cada deploy e mente sobre o histórico), nem
+ * valor derivado de suposição sobre comportamento humano.
+ *
+ * Essa disciplina custa: a métrica que o produto mais gostaria de mostrar —
+ * "minutos de trabalho economizados" — não existe aqui, porque ela exige um
+ * baseline humano que ninguém mediu. Inventar um multiplicador ("cada nota
+ * baixada à mão leva 4 minutos") produziria um número bonito, citável e falso, e
+ * a primeira pessoa a cronometrar o próprio trabalho descobriria a fraude.
+ *
+ * O que existe é a MEDIÇÃO PRONTA: o denominador e o numerador estão
+ * registrados, e no dia em que alguém cronometrar o trabalho manual real, a
+ * conta fecha sem precisar de schema novo.
+ */
+export interface FiscalOperationalMetrics {
+    /** Execuções registradas, por desfecho. */
+    runsTotal: number;
+    runsSuccess: number;
+    runsFailure: number;
+    runsBlocked: number;
+    documentsFetched: number;
+    documentsNew: number;
+    documentsDuplicate: number;
+    documentsFailed: number;
+    eventsPending: number;
+    eventsApplied: number;
+    eventsReconciled: number;
+    providerErrors: number;
+    /** Milissegundos. `null` quando nenhuma execução mediu duração. */
+    syncDurationMsP50: number | null;
+    syncDurationMsMax: number | null;
+    lastSuccessfulSyncAt: string | null;
+    /** Vezes tomadas de titulares que não as devolveram. Worker morrendo. */
+    leaseRecoveries: number;
+    staleLeases: number;
+    openInterventions: number;
+    openCircuits: number;
+}
+export declare function fiscalOperationalMetrics(tx: Tx, now?: Date): Promise<FiscalOperationalMetrics>;
+/**
+ * As métricas de VALOR — e a honestidade sobre o que cada uma prova.
+ *
+ * Cada campo vem com o que ele significa exatamente, porque a diferença entre
+ * "documento coletado" e "download evitado" é onde um painel de produto começa a
+ * mentir sem que ninguém tenha mentido de propósito.
+ */
+export interface FiscalValueMetrics {
+    /**
+     * Documentos que chegaram por automação. Fato direto: linhas de
+     * `fiscal_document` cuja origem não é entrega manual.
+     */
+    documentsAutomaticallyCollected: number;
+    /**
+     * Downloads de portal evitados.
+     *
+     * DEFINIÇÃO: um documento coletado automaticamente COM o XML original
+     * preservado é um arquivo que ninguém precisou baixar. É medição de arquivo,
+     * não de tempo — e a distinção importa: um resumo (`summary`) coletado ainda
+     * exigiria alguém buscar o documento completo, então ele não conta.
+     */
+    manualDownloadsAvoided: number;
+    /**
+     * Pedidos ao cliente evitados — PARCIAL, e por um motivo que não some.
+     *
+     * O numerador é medível: competências de `docs_fiscais_mes` cuja coleta
+     * automática trouxe documento. O que NÃO é medível é se o escritório de fato
+     * teria pedido ao cliente naquela competência — isso depende de uma rotina
+     * humana que ninguém registrou. O número abaixo é um limite SUPERIOR honesto,
+     * e o campo `basis` diz isso em voz alta.
+     */
+    clientRequestsAvoided: number;
+    clientRequestsAvoidedBasis: 'upper_bound_no_human_baseline';
+    /**
+     * Intervenções humanas exigidas. Fato direto, e o contrapeso das outras três:
+     * automação que gera tarefa não economizou nada.
+     */
+    humanInterventionsRequired: number;
+    humanInterventionsResolved: number;
+    /**
+     * O que NÃO está aqui, e por quê.
+     *
+     * `estimatedMinutesSaved` exigiria cronometrar o trabalho manual real. Sem
+     * esse baseline, qualquer número seria um multiplicador inventado — e o campo
+     * declara a ausência em vez de deixar quem lê supor que esquecemos.
+     */
+    estimatedMinutesSaved: null;
+    minutesSavedBlockedBy: 'human_baseline_not_measured';
+}
+export declare function fiscalValueMetrics(tx: Tx): Promise<FiscalValueMetrics>;
+/**
+ * O estado operacional de UM cliente.
+ *
+ * ## Nenhum destes é um semáforo inventado
+ *
+ * Cada valor sai de um fato do banco, e a ordem de avaliação vai do mais
+ * específico ao mais genérico — dizer "erro" quando na verdade ninguém ligou a
+ * automação seria culpar o sistema pela ausência de decisão de uma pessoa.
+ *
+ *   `DISABLED`      sem política de cadência. Escolha legítima.
+ *   `UNSUPPORTED`   não há caminho de coleta conhecido para este cliente.
+ *   `AUTH_REQUIRED` credencial vencida, inválida ou recusada.
+ *   `SYNCING`       há uma vez tomada e viva neste instante.
+ *   `ERROR`         a última execução falhou e ninguém resolveu.
+ *   `DEGRADED`      há execução recente boa E fila humana aberta.
+ *   `HEALTHY`       sincronizou com sucesso na última vez.
+ *   `READY`         tudo em ordem e nenhuma execução ainda.
+ */
+export type FiscalClientOperationalStatus = 'DISABLED' | 'READY' | 'SYNCING' | 'HEALTHY' | 'DEGRADED' | 'AUTH_REQUIRED' | 'ERROR' | 'UNSUPPORTED';
+export interface FiscalClientSyncRow {
+    clientId: string;
+    clientName: string | null;
+    documentType: FiscalDocumentType;
+    source: string | null;
+    environment: string | null;
+    status: FiscalClientOperationalStatus;
+    frequency: string;
+    lastSuccessAt: string | null;
+    lastStartedAt: string | null;
+    nextRunAt: string | null;
+    lastErrorClass: string | null;
+    consecutiveFailures: number;
+    cursor: string | null;
+    documentsCollected: number;
+    openInterventions: number;
+    coverageStatus: string;
+    leaseHolder: string | null;
+    detail: string;
+}
+/**
+ * O painel por cliente.
+ *
+ * Uma consulta só, e não N+1: a tela lista a carteira inteira, e um `for` com
+ * quatro consultas por cliente transformaria trinta clientes em cento e vinte
+ * viagens ao banco. A cobertura entra por junção lateral com a MESMA regra do
+ * módulo de cobertura — pergunta municipal só é respondida por linha municipal.
+ */
+export declare function listFiscalClientSyncStatus(tx: Tx, input?: {
+    documentType?: FiscalDocumentType;
+    now?: Date;
+}): Promise<FiscalClientSyncRow[]>;
+//# sourceMappingURL=observability.d.ts.map

package/dist/fiscal/sync/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../../src/fiscal/sync/observability.ts"],"names":[],"mappings":"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"}

package/dist/fiscal/sync/observability.js

@@ -0,0 +1,239 @@
+export async function fiscalOperationalMetrics(tx, now = new Date()) {
+    const [runs] = await tx `
+    SELECT count(*)::int                                                             AS total,
+           count(*) FILTER (WHERE outcome IN ('completed','no_documents'))::int      AS success,
+           count(*) FILTER (WHERE outcome IN ('failed','provider_error'))::int       AS failure,
+           count(*) FILTER (WHERE outcome LIKE 'blocked%' OR outcome = 'throttled')::int
+                                                                                     AS blocked,
+           coalesce(sum(documents_fetched), 0)::int                                  AS fetched,
+           coalesce(sum(documents_new), 0)::int                                      AS novos,
+           coalesce(sum(documents_duplicate), 0)::int                                AS dup,
+           coalesce(sum(documents_failed), 0)::int                                   AS falhos,
+           coalesce(sum(events_pending), 0)::int                                     AS pend,
+           coalesce(sum(events_applied), 0)::int                                     AS apl,
+           coalesce(sum(events_reconciled), 0)::int                                  AS rec,
+           count(*) FILTER (WHERE outcome = 'provider_error')::int                   AS prov,
+           -- Percentil, e não média: uma execução de dez minutos entre mil de um
+           -- segundo move a média e não move a mediana — e é a mediana que
+           -- descreve o que acontece na maioria das vezes.
+           (percentile_disc(0.5) WITHIN GROUP (ORDER BY duration_ms)
+              FILTER (WHERE duration_ms IS NOT NULL))::int                           AS p50,
+           max(duration_ms)::int                                                     AS max,
+           max(finished_at) FILTER (WHERE outcome IN ('completed','no_documents'))   AS ultimo
+      FROM fiscal_sync_run
+  `;
+    const [leases] = await tx `
+    SELECT coalesce(sum(recovered_count), 0)::int                                    AS recuperacoes,
+           count(*) FILTER (WHERE released_at IS NULL AND expires_at <= ${now})::int AS vencidos
+      FROM fiscal_sync_lease
+  `;
+    const [fila] = await tx `
+    SELECT count(*)::int AS abertas FROM fiscal_intervention WHERE state <> 'resolved'
+  `;
+    const [circuitos] = await tx `
+    SELECT count(*)::int AS abertos
+      FROM fiscal_provider_circuit
+     WHERE state = 'open' AND (open_until IS NULL OR open_until > ${now})
+  `;
+    return {
+        runsTotal: runs?.total ?? 0,
+        runsSuccess: runs?.success ?? 0,
+        runsFailure: runs?.failure ?? 0,
+        runsBlocked: runs?.blocked ?? 0,
+        documentsFetched: runs?.fetched ?? 0,
+        documentsNew: runs?.novos ?? 0,
+        documentsDuplicate: runs?.dup ?? 0,
+        documentsFailed: runs?.falhos ?? 0,
+        eventsPending: runs?.pend ?? 0,
+        eventsApplied: runs?.apl ?? 0,
+        eventsReconciled: runs?.rec ?? 0,
+        providerErrors: runs?.prov ?? 0,
+        syncDurationMsP50: runs?.p50 ?? null,
+        syncDurationMsMax: runs?.max ?? null,
+        lastSuccessfulSyncAt: runs?.ultimo?.toISOString() ?? null,
+        leaseRecoveries: leases?.recuperacoes ?? 0,
+        staleLeases: leases?.vencidos ?? 0,
+        openInterventions: fila?.abertas ?? 0,
+        openCircuits: circuitos?.abertos ?? 0,
+    };
+}
+export async function fiscalValueMetrics(tx) {
+    const [docs] = await tx `
+    SELECT count(*) FILTER (WHERE source <> 'manual')::int                       AS automaticos,
+           count(*) FILTER (WHERE source <> 'manual' AND raw_blob_id IS NOT NULL
+                              AND content_kind = 'full')::int                    AS "comRaw"
+      FROM fiscal_document
+  `;
+    const [pedidos] = await tx `
+    -- Competências de "Documentos fiscais do mês" em que a automação trouxe ao
+    -- menos um documento daquele cliente. A junção é pela COMPETÊNCIA, não pela
+    -- data de emissão: são conceitos independentes, e confundi-los erraria o
+    -- fechamento (a mesma distinção que a 0056 registra em competence_label).
+    SELECT count(DISTINCT (ri.client_id, c.label))::int AS n
+      FROM recurring_instance ri
+      JOIN recurring_item_type rit ON rit.id = ri.item_type_id
+      JOIN competence c ON c.id = ri.competence_id
+     WHERE rit.key = 'docs_fiscais_mes'
+       AND ri.deleted_at IS NULL
+       AND EXISTS (
+         SELECT 1 FROM fiscal_document fd
+          WHERE fd.client_id = ri.client_id
+            AND fd.competence_label = c.label
+            AND fd.source <> 'manual'
+       )
+  `;
+    const [fila] = await tx `
+    SELECT count(*) FILTER (WHERE state <> 'resolved')::int AS abertas,
+           count(*) FILTER (WHERE state = 'resolved')::int  AS resolvidas
+      FROM fiscal_intervention
+  `;
+    return {
+        documentsAutomaticallyCollected: docs?.automaticos ?? 0,
+        manualDownloadsAvoided: docs?.comRaw ?? 0,
+        clientRequestsAvoided: pedidos?.n ?? 0,
+        clientRequestsAvoidedBasis: 'upper_bound_no_human_baseline',
+        humanInterventionsRequired: fila?.abertas ?? 0,
+        humanInterventionsResolved: fila?.resolvidas ?? 0,
+        estimatedMinutesSaved: null,
+        minutesSavedBlockedBy: 'human_baseline_not_measured',
+    };
+}
+/**
+ * O painel por cliente.
+ *
+ * Uma consulta só, e não N+1: a tela lista a carteira inteira, e um `for` com
+ * quatro consultas por cliente transformaria trinta clientes em cento e vinte
+ * viagens ao banco. A cobertura entra por junção lateral com a MESMA regra do
+ * módulo de cobertura — pergunta municipal só é respondida por linha municipal.
+ */
+export async function listFiscalClientSyncStatus(tx, input = {}) {
+    const documentType = input.documentType ?? 'nfse';
+    const now = input.now ?? new Date();
+    const rows = await tx `
+    SELECT c.id                                   AS client_id,
+           c.display_name                         AS client_name,
+           c.municipality_ibge_code,
+           cur.source,
+           cur.environment,
+           pol.frequency,
+           cur.last_success_at,
+           cur.last_started_at,
+           cur.next_attempt_after,
+           cur.next_eligible_run_at,
+           cur.last_error_class,
+           cur.consecutive_failures,
+           cur.last_nsu,
+           (SELECT count(*)::int FROM fiscal_document d
+             WHERE d.client_id = c.id AND d.document_type = ${documentType}) AS documentos,
+           (SELECT count(*)::int FROM fiscal_intervention i
+             WHERE i.client_id = c.id AND i.state <> 'resolved')             AS intervencoes,
+           (SELECT bool_or(i.kind IN ('certificate_expired','certificate_invalid','auth_required'))
+              FROM fiscal_intervention i
+             WHERE i.client_id = c.id AND i.state <> 'resolved')             AS cred_expirada,
+           (SELECT l.holder FROM fiscal_sync_lease l
+             WHERE l.client_id = c.id AND l.document_type = ${documentType}
+               AND l.released_at IS NULL AND l.expires_at > ${now}
+             LIMIT 1)                                                        AS lease_holder,
+           cov.coverage_status
+      FROM client c
+      JOIN client_fiscal_enrollment e
+        ON e.client_id = c.id AND e.document_type = ${documentType} AND e.revoked_at IS NULL
+      LEFT JOIN fiscal_sync_cursor cur
+        ON cur.client_id = c.id AND cur.environment = (
+             SELECT mode FROM tenant_fiscal_automation LIMIT 1
+           )
+      LEFT JOIN LATERAL (
+        SELECT frequency FROM fiscal_sync_policy p
+         WHERE p.document_type = ${documentType}
+           AND (p.client_id = c.id OR p.client_id IS NULL)
+         ORDER BY p.client_id NULLS LAST
+         LIMIT 1
+      ) pol ON true
+      LEFT JOIN LATERAL (
+        -- A MESMA regra do módulo de cobertura, e a razão de ela estar repetida
+        -- aqui é performance de listagem: uma pergunta municipal só encontra
+        -- linha municipal (a exata do IBGE, senão a padrão). Nunca sobe para a
+        -- nacional — é assim que "o ADN cobre o Brasil inteiro" entraria.
+        SELECT fc.coverage_status
+          FROM fiscal_coverage fc
+         WHERE fc.document_type = ${documentType}
+           AND fc.jurisdiction_scope = ${documentType === 'nfse' ? 'municipal' : 'national'}
+           AND (fc.jurisdiction_code = c.municipality_ibge_code OR fc.jurisdiction_code IS NULL)
+         ORDER BY fc.jurisdiction_code NULLS LAST
+         LIMIT 1
+      ) cov ON true
+     WHERE c.deleted_at IS NULL
+     ORDER BY c.display_name
+  `;
+    return rows.map((r) => {
+        const cobertura = r.coverage_status ?? 'UNKNOWN';
+        const frequency = r.frequency ?? 'disabled';
+        const gate = maior(r.next_eligible_run_at, r.next_attempt_after);
+        const status = (() => {
+            if (r.cred_expirada)
+                return 'AUTH_REQUIRED';
+            if (cobertura === 'UNSUPPORTED')
+                return 'UNSUPPORTED';
+            if (frequency === 'disabled')
+                return 'DISABLED';
+            if (r.lease_holder)
+                return 'SYNCING';
+            if (r.last_error_class)
+                return 'ERROR';
+            if (r.last_success_at)
+                return (r.intervencoes ?? 0) > 0 ? 'DEGRADED' : 'HEALTHY';
+            return 'READY';
+        })();
+        return {
+            clientId: r.client_id,
+            clientName: r.client_name,
+            documentType,
+            source: r.source,
+            environment: r.environment,
+            status,
+            frequency,
+            lastSuccessAt: r.last_success_at?.toISOString() ?? null,
+            lastStartedAt: r.last_started_at?.toISOString() ?? null,
+            nextRunAt: gate?.toISOString() ?? null,
+            lastErrorClass: r.last_error_class,
+            consecutiveFailures: r.consecutive_failures ?? 0,
+            cursor: r.last_nsu,
+            documentsCollected: r.documentos,
+            openInterventions: r.intervencoes,
+            coverageStatus: cobertura,
+            leaseHolder: r.lease_holder,
+            detail: describe(status, cobertura, frequency),
+        };
+    });
+}
+function maior(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return a > b ? a : b;
+}
+/** A frase que explica o estado. Fato, nunca conselho genérico. */
+function describe(status, coverage, frequency) {
+    switch (status) {
+        case 'DISABLED':
+            return 'Cadência desligada. Inscrever o cliente não liga a busca automática.';
+        case 'UNSUPPORTED':
+            return 'Não há caminho de coleta automática conhecido para esta jurisdição.';
+        case 'AUTH_REQUIRED':
+            return 'Certificado vencido, inválido ou recusado. Só uma pessoa resolve.';
+        case 'SYNCING':
+            return 'Uma execução está com a vez deste fluxo agora.';
+        case 'ERROR':
+            return 'A última execução falhou. O cursor não avançou — nada foi perdido.';
+        case 'DEGRADED':
+            return 'A última execução deu certo, mas há pendência humana aberta.';
+        case 'HEALTHY':
+            return `Sincronizando em cadência ${frequency}.`;
+        case 'READY':
+            return coverage === 'UNKNOWN'
+                ? 'Habilitado, mas a cobertura desta jurisdição é desconhecida.'
+                : 'Habilitado e ainda sem execução concluída.';
+    }
+}
+//# sourceMappingURL=observability.js.map

package/dist/fiscal/sync/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../../../src/fiscal/sync/observability.ts"],"names":[],"mappings":"AAgDA,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,EAAM,EACN,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAkBtB;;;;;;;;;;;;;;;;;;;;;;GAsBA,CAAC;IAEF,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAA8C;;0EAEC,GAAG;;GAE1E,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAuB;;GAE7C,CAAC;IACF,MAAM,CAAC,SAAS,CAAC,GAAG,MAAM,EAAE,CAAuB;;;oEAGe,GAAG;GACpE,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;QAC3B,WAAW,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QAC/B,WAAW,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QAC/B,WAAW,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QAC/B,gBAAgB,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QACpC,YAAY,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;QAC9B,kBAAkB,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAClC,eAAe,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;QAClC,aAAa,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QAC9B,aAAa,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAC7B,gBAAgB,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;QAChC,cAAc,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;QAC/B,iBAAiB,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI;QACpC,iBAAiB,EAAE,IAAI,EAAE,GAAG,IAAI,IAAI;QACpC,oBAAoB,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,IAAI;QACzD,eAAe,EAAE,MAAM,EAAE,YAAY,IAAI,CAAC;QAC1C,WAAW,EAAE,MAAM,EAAE,QAAQ,IAAI,CAAC;QAClC,iBAAiB,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QACrC,YAAY,EAAE,SAAS,EAAE,OAAO,IAAI,CAAC;KACtC,CAAC;AACJ,CAAC;AAoDD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAM;IAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAA2C;;;;;GAKjE,CAAC;IACF,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,EAAE,CAAiB;;;;;;;;;;;;;;;;;GAiB1C,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAA2C;;;;GAIjE,CAAC;IAEF,OAAO;QACL,+BAA+B,EAAE,IAAI,EAAE,WAAW,IAAI,CAAC;QACvD,sBAAsB,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;QACzC,qBAAqB,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC;QACtC,0BAA0B,EAAE,+BAA+B;QAC3D,0BAA0B,EAAE,IAAI,EAAE,OAAO,IAAI,CAAC;QAC9C,0BAA0B,EAAE,IAAI,EAAE,UAAU,IAAI,CAAC;QACjD,qBAAqB,EAAE,IAAI;QAC3B,qBAAqB,EAAE,6BAA6B;KACrD,CAAC;AACJ,CAAC;AAmDD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,EAAM,EACN,QAA2D,EAAE;IAE7D,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,MAAM,CAAC;IAClD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IAEpC,MAAM,IAAI,GAAG,MAAM,EAAE,CAqBpB;;;;;;;;;;;;;;;8DAe2D,YAAY;;;;;;;8DAOZ,YAAY;8DACZ,GAAG;;;;;sDAKX,YAAY;;;;;;;mCAO/B,YAAY;;;;;;;;;;;;oCAYX,YAAY;yCACP,YAAY,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU;;;;;;;GAOxF,CAAC;IAEF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,MAAM,SAAS,GAAG,CAAC,CAAC,eAAe,IAAI,SAAS,CAAC;QACjD,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,IAAI,UAAU,CAAC;QAC5C,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,oBAAoB,EAAE,CAAC,CAAC,kBAAkB,CAAC,CAAC;QAEjE,MAAM,MAAM,GAAkC,CAAC,GAAG,EAAE;YAClD,IAAI,CAAC,CAAC,aAAa;gBAAE,OAAO,eAAe,CAAC;YAC5C,IAAI,SAAS,KAAK,aAAa;gBAAE,OAAO,aAAa,CAAC;YACtD,IAAI,SAAS,KAAK,UAAU;gBAAE,OAAO,UAAU,CAAC;YAChD,IAAI,CAAC,CAAC,YAAY;gBAAE,OAAO,SAAS,CAAC;YACrC,IAAI,CAAC,CAAC,gBAAgB;gBAAE,OAAO,OAAO,CAAC;YACvC,IAAI,CAAC,CAAC,eAAe;gBAAE,OAAO,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;YACjF,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC,EAAE,CAAC;QAEL,OAAO;YACL,QAAQ,EAAE,CAAC,CAAC,SAAS;YACrB,UAAU,EAAE,CAAC,CAAC,WAAW;YACzB,YAAY;YACZ,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,MAAM;YACN,SAAS;YACT,aAAa,EAAE,CAAC,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,IAAI;YACvD,aAAa,EAAE,CAAC,CAAC,eAAe,EAAE,WAAW,EAAE,IAAI,IAAI;YACvD,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,IAAI;YACtC,cAAc,EAAE,CAAC,CAAC,gBAAgB;YAClC,mBAAmB,EAAE,CAAC,CAAC,oBAAoB,IAAI,CAAC;YAChD,MAAM,EAAE,CAAC,CAAC,QAAQ;YAClB,kBAAkB,EAAE,CAAC,CAAC,UAAU;YAChC,iBAAiB,EAAE,CAAC,CAAC,YAAY;YACjC,cAAc,EAAE,SAAS;YACzB,WAAW,EAAE,CAAC,CAAC,YAAY;YAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC;SAC/C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,KAAK,CAAC,CAAc,EAAE,CAAc;IAC3C,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,mEAAmE;AACnE,SAAS,QAAQ,CACf,MAAqC,EACrC,QAAgB,EAChB,SAAiB;IAEjB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,UAAU;YACb,OAAO,sEAAsE,CAAC;QAChF,KAAK,aAAa;YAChB,OAAO,qEAAqE,CAAC;QAC/E,KAAK,eAAe;YAClB,OAAO,mEAAmE,CAAC;QAC7E,KAAK,SAAS;YACZ,OAAO,gDAAgD,CAAC;QAC1D,KAAK,OAAO;YACV,OAAO,oEAAoE,CAAC;QAC9E,KAAK,UAAU;YACb,OAAO,8DAA8D,CAAC;QACxE,KAAK,SAAS;YACZ,OAAO,6BAA6B,SAAS,GAAG,CAAC;QACnD,KAAK,OAAO;YACV,OAAO,QAAQ,KAAK,SAAS;gBAC3B,CAAC,CAAC,8DAA8D;gBAChE,CAAC,CAAC,4CAA4C,CAAC;IACrD,CAAC;AACH,CAAC"}