@baruk/core 0.4.2 → 0.5.0

package/dist/cjs/fiscal/sync/intervention.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.raiseFiscalIntervention = raiseFiscalIntervention;
+exports.resolveFiscalInterventions = resolveFiscalInterventions;
+exports.listFiscalInterventions = listFiscalInterventions;
+const shared_1 = require("@baruk/shared");
+/**
+ * Abre a tarefa, ou soma uma ocorrência à que já existe.
+ *
+ * `detail` é atualizado a cada ocorrência: o motivo mais recente é o mais útil
+ * para quem for resolver. É CLASSE e contexto — nunca a resposta do provedor,
+ * que cita sujeito de certificado e caminho de arquivo.
+ */
+async function raiseFiscalIntervention(tx, input) {
+    const now = input.now ?? new Date();
+    // O índice único é parcial (`WHERE state <> 'resolved'`), então `ON CONFLICT`
+    // não o alcança por nome de coluna. O caminho é tentar o UPDATE primeiro e
+    // inserir só quando ninguém foi atingido — nesta ordem, porque a inversa
+    // dispararia violação de unicidade no caso comum (a tarefa já existe).
+    const atualizados = await tx `
+    UPDATE fiscal_intervention
+       SET occurrences = occurrences + 1, last_seen_at = ${now}, detail = ${input.detail}
+     WHERE state <> 'resolved'
+       AND kind = ${input.kind}
+       AND client_id IS NOT DISTINCT FROM ${input.clientId ?? null}
+       AND source IS NOT DISTINCT FROM ${input.source ?? null}
+       AND environment IS NOT DISTINCT FROM ${input.environment ?? null}
+    RETURNING id, occurrences
+  `;
+    const existente = atualizados[0];
+    if (existente) {
+        return { id: existente.id, created: false, occurrences: existente.occurrences };
+    }
+    /*
+     * A corrida que o lease NÃO cobre.
+     *
+     * A vez de sincronizar é tomada DEPOIS do portão de credencial — de propósito,
+     * porque não faz sentido travar um cliente para descobrir em seguida que o
+     * certificado dele venceu. A consequência é que dois workers podem chegar a
+     * este ponto ao mesmo tempo para o mesmo cliente: os dois não encontram
+     * pendência aberta, e os dois tentam inserir.
+     *
+     * O segundo bate no índice único parcial. Sem tratamento, a exceção aborta a
+     * transação inteira e o ciclo daquele escritório cai — um erro de
+     * infraestrutura produzido por dois processos concordando sobre um fato.
+     *
+     * O `SAVEPOINT` é o que torna a recuperação possível: no PostgreSQL um comando
+     * que falha aborta a transação, e daí em diante todo comando devolve `25P02`
+     * — inclusive o UPDATE de recuperação. Com savepoint, só a tentativa de
+     * inserção é desfeita.
+     */
+    const id = (0, shared_1.uuidv7)();
+    try {
+        await tx.savepoint((sp) => sp `
+      INSERT INTO fiscal_intervention (
+        id, tenant_id, client_id, kind, source, environment, document_type,
+        state, detail, occurrences, first_seen_at, last_seen_at
+      ) VALUES (
+        ${id}, ${input.tenantId}, ${input.clientId ?? null}, ${input.kind},
+        ${input.source ?? null}, ${input.environment ?? null}, ${input.documentType ?? null},
+        'open', ${input.detail}, 1, ${now}, ${now}
+      )
+    `);
+        return { id, created: true, occurrences: 1 };
+    }
+    catch (err) {
+        // `23505` é violação de unicidade: alguém abriu a MESMA pendência entre o
+        // nosso UPDATE e o nosso INSERT. O desfecho correto é o mesmo do caminho
+        // comum — somar uma ocorrência à linha que agora existe.
+        const code = err?.code;
+        if (code !== '23505')
+            throw err;
+        const concorrente = await tx `
+      UPDATE fiscal_intervention
+         SET occurrences = occurrences + 1, last_seen_at = ${now}, detail = ${input.detail}
+       WHERE state <> 'resolved'
+         AND kind = ${input.kind}
+         AND client_id IS NOT DISTINCT FROM ${input.clientId ?? null}
+         AND source IS NOT DISTINCT FROM ${input.source ?? null}
+         AND environment IS NOT DISTINCT FROM ${input.environment ?? null}
+      RETURNING id, occurrences
+    `;
+        const linha = concorrente[0];
+        if (linha)
+            return { id: linha.id, created: false, occurrences: linha.occurrences };
+        // Nem inseriu nem encontrou: alguém resolveu a pendência no intervalo. Não é
+        // erro, e não vale reabrir — o problema deixou de existir para quem olhou.
+        return { id, created: false, occurrences: 0 };
+    }
+}
+/**
+ * Fecha a tarefa quando o problema deixou de existir.
+ *
+ * Fechamento AUTOMÁTICO só para o que foi observado voltar a funcionar — nunca
+ * por decurso de prazo. Uma tarefa que some sozinha depois de uma semana é uma
+ * tarefa que ninguém resolveu, apresentada como resolvida.
+ */
+async function resolveFiscalInterventions(tx, input) {
+    if (input.kinds.length === 0)
+        return 0;
+    const now = input.now ?? new Date();
+    const rows = await tx `
+    UPDATE fiscal_intervention
+       SET state = 'resolved', resolved_at = ${now}, resolved_by = ${input.resolvedBy ?? null}
+     WHERE state <> 'resolved'
+       AND kind = ANY (${input.kinds})
+       AND client_id IS NOT DISTINCT FROM ${input.clientId ?? null}
+       AND source IS NOT DISTINCT FROM ${input.source ?? null}
+       AND environment IS NOT DISTINCT FROM ${input.environment ?? null}
+    RETURNING id
+  `;
+    return rows.length;
+}
+/** A fila aberta do escritório, a mais recente primeiro. */
+async function listFiscalInterventions(tx, input = {}) {
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+    const state = input.state ?? 'open';
+    const rows = await tx `
+    SELECT id, client_id, kind, source, environment, document_type, state, detail,
+           occurrences, first_seen_at, last_seen_at
+      FROM fiscal_intervention
+     WHERE ${state === 'any' ? tx `true` : tx `state = ${state}`}
+     ORDER BY last_seen_at DESC
+     LIMIT ${limit}
+  `;
+    return rows.map((r) => ({
+        id: r.id,
+        clientId: r.client_id,
+        kind: r.kind,
+        source: r.source,
+        environment: r.environment,
+        documentType: r.document_type,
+        state: r.state,
+        detail: r.detail,
+        occurrences: r.occurrences,
+        firstSeenAt: r.first_seen_at.toISOString(),
+        lastSeenAt: r.last_seen_at.toISOString(),
+    }));
+}
+//# sourceMappingURL=intervention.js.map

package/dist/cjs/fiscal/sync/intervention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intervention.js","sourceRoot":"","sources":["../../../../src/fiscal/sync/intervention.ts"],"names":[],"mappings":";;AA0DA,0DAyFC;AASD,gEAwBC;AAGD,0DAyCC;AAhOD,0CAAuC;AAmDvC;;;;;;GAMG;AACI,KAAK,UAAU,uBAAuB,CAC3C,EAAM,EACN,KASC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACpC,8EAA8E;IAC9E,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,MAAM,WAAW,GAAG,MAAM,EAAE,CAAuC;;2DAEV,GAAG,cAAc,KAAK,CAAC,MAAM;;oBAEpE,KAAK,CAAC,IAAI;4CACc,KAAK,CAAC,QAAQ,IAAI,IAAI;yCACzB,KAAK,CAAC,MAAM,IAAI,IAAI;8CACf,KAAK,CAAC,WAAW,IAAI,IAAI;;GAEpE,CAAC;IACF,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC;IAClF,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,EAAE,GAAG,IAAA,eAAM,GAAE,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAChB,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAA;;;;;UAKN,EAAE,KAAK,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,IAAI,IAAI,KAAK,KAAK,CAAC,IAAI;UAC/D,KAAK,CAAC,MAAM,IAAI,IAAI,KAAK,KAAK,CAAC,WAAW,IAAI,IAAI,KAAK,KAAK,CAAC,YAAY,IAAI,IAAI;kBACzE,KAAK,CAAC,MAAM,QAAQ,GAAG,KAAK,GAAG;;KAE5C,CACA,CAAC;QACF,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,yEAAyE;QACzE,yDAAyD;QACzD,MAAM,IAAI,GAAI,GAAgC,EAAE,IAAI,CAAC;QACrD,IAAI,IAAI,KAAK,OAAO;YAAE,MAAM,GAAG,CAAC;QAEhC,MAAM,WAAW,GAAG,MAAM,EAAE,CAAuC;;6DAEV,GAAG,cAAc,KAAK,CAAC,MAAM;;sBAEpE,KAAK,CAAC,IAAI;8CACc,KAAK,CAAC,QAAQ,IAAI,IAAI;2CACzB,KAAK,CAAC,MAAM,IAAI,IAAI;gDACf,KAAK,CAAC,WAAW,IAAI,IAAI;;KAEpE,CAAC;QACF,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,KAAK;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;QACnF,6EAA6E;QAC7E,2EAA2E;QAC3E,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAChD,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,0BAA0B,CAC9C,EAAM,EACN,KAOC;IAED,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,EAAE,CAAkB;;+CAEM,GAAG,mBAAmB,KAAK,CAAC,UAAU,IAAI,IAAI;;yBAEpE,KAAK,CAAC,KAAiB;4CACJ,KAAK,CAAC,QAAQ,IAAI,IAAI;yCACzB,KAAK,CAAC,MAAM,IAAI,IAAI;8CACf,KAAK,CAAC,WAAW,IAAI,IAAI;;GAEpE,CAAC;IACF,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAED,4DAA4D;AACrD,KAAK,UAAU,uBAAuB,CAC3C,EAAM,EACN,QAA+D,EAAE;IAEjE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC;IACpC,MAAM,IAAI,GAAG,MAAM,EAAE,CAcpB;;;;aAIU,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA,MAAM,CAAC,CAAC,CAAC,EAAE,CAAA,WAAW,KAAK,EAAE;;aAEjD,KAAK;GACf,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtB,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,QAAQ,EAAE,CAAC,CAAC,SAAS;QACrB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,YAAY,EAAE,CAAC,CAAC,aAAa;QAC7B,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,aAAa,CAAC,WAAW,EAAE;QAC1C,UAAU,EAAE,CAAC,CAAC,YAAY,CAAC,WAAW,EAAE;KACzC,CAAC,CAAC,CAAC;AACN,CAAC"}

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

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LEASE_TTL_MS = void 0;
+exports.acquireFiscalSyncLease = acquireFiscalSyncLease;
+exports.heartbeatFiscalSyncLease = heartbeatFiscalSyncLease;
+exports.releaseFiscalSyncLease = releaseFiscalSyncLease;
+exports.listStaleFiscalSyncLeases = listStaleFiscalSyncLeases;
+const shared_1 = require("@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`.
+ */
+exports.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.
+ */
+async function acquireFiscalSyncLease(tx, input) {
+    const now = input.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + (input.ttlMs ?? exports.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 (
+      ${(0, shared_1.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.
+ */
+async function heartbeatFiscalSyncLease(tx, input) {
+    const now = input.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + (input.ttlMs ?? exports.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.
+ */
+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.
+ */
+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/cjs/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/cjs/fiscal/sync/observability.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fiscalOperationalMetrics = fiscalOperationalMetrics;
+exports.fiscalValueMetrics = fiscalValueMetrics;
+exports.listFiscalClientSyncStatus = listFiscalClientSyncStatus;
+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,
+    };
+}
+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.
+ */
+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/cjs/fiscal/sync/observability.js.map

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