@baruk/core 0.4.2 → 0.5.0

package/dist/fiscal/contracts/nfse-adn-envelope.js

@@ -0,0 +1,215 @@
+import { gunzipSync } from 'node:zlib';
+import { FiscalProviderError, } from '../ingestion/provider.js';
+import { NFSE_ADN_LIMITS, NFSE_ADN_OFFICIAL_CODES, } from './nfse-adn-contract.js';
+/**
+ * A resposta não corresponde ao contrato declarado.
+ *
+ * Classe `invalid` porque retentar não resolve: o formato não muda entre
+ * tentativas. `providerCode` é SEMPRE `PROTOCOL_CONTRACT_MISMATCH` — um código
+ * único é o que permite ao painel perguntar "o contrato quebrou?" com uma
+ * comparação de igualdade. O detalhe fica em `reason`, que é enumerado e não
+ * carrega um byte do corpo recebido: um corpo hostil não escreve na nossa trilha.
+ */
+export class AdnContractMismatchError extends FiscalProviderError {
+    reason;
+    profileId;
+    constructor(reason, profileId) {
+        super('invalid', `resposta do ADN não corresponde ao perfil ${profileId} (${reason})`, 'PROTOCOL_CONTRACT_MISMATCH');
+        this.reason = reason;
+        this.profileId = profileId;
+        this.name = 'AdnContractMismatchError';
+    }
+}
+/** Base64 canônico. `Buffer.from(x,'base64')` ignora lixo em silêncio — este não. */
+const BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Assinatura do gzip (RFC 1952 §2.3.1): `1f 8b`. Dois bytes, sem ambiguidade. */
+const GZIP_MAGIC = [0x1f, 0x8b];
+/**
+ * Lê o envelope. Devolve lote (possivelmente vazio e RECONHECIDO), ou lança.
+ *
+ * Nunca devolve `documents: []` para uma resposta que não entendeu. Essa é a
+ * invariante, e o teste de mutação da Fase 3 a exercita reintroduzindo o
+ * comportamento antigo e exigindo que a suíte fique vermelha.
+ */
+export function readAdnEnvelope(body, options) {
+    const { profile, fromNsu } = options;
+    const maxBytes = options.maxResponseBytes ?? NFSE_ADN_LIMITS.maxResponseBytes.value;
+    const maxDoc = options.maxDecompressedBytesPerDocument ??
+        NFSE_ADN_LIMITS.maxDecompressedBytesPerDocument.value;
+    const maxLote = options.maxDecompressedBytesPerBatch ?? NFSE_ADN_LIMITS.maxDecompressedBytesPerBatch.value;
+    const maxItens = options.maxDocumentsPerBatch ?? NFSE_ADN_LIMITS.maxDocumentsPerBatch.value;
+    // A anotação de tipo explícita não é decoração: sem ela o TypeScript não
+    // propaga o `never` de uma arrow function, e todo `if (...) recusa(...)`
+    // deixaria de estreitar o tipo depois — obrigando a um `return` ou a um `!`
+    // em cada ponto, que é exatamente onde um dia alguém erra.
+    const recusa = (r) => {
+        throw new AdnContractMismatchError(r, profile.id);
+    };
+    if (body.byteLength > maxBytes)
+        recusa('RESPONSE_TOO_LARGE');
+    if (body.byteLength === 0)
+        recusa('BODY_EMPTY');
+    const texto = Buffer.from(body).toString('utf8').trim();
+    // Página de erro de proxy, portal de captura, HTML de WAF. Todos começam com
+    // `<`, e todos seriam "JSON inválido" — um diagnóstico que manda a pessoa
+    // olhar o lugar errado. Nomear o caso aponta para a rede, não para o parser.
+    if (texto.startsWith('<'))
+        recusa('MARKUP_INSTEAD_OF_JSON');
+    let json;
+    try {
+        json = JSON.parse(texto);
+    }
+    catch {
+        recusa('NOT_JSON');
+    }
+    if (json === null || typeof json !== 'object' || Array.isArray(json))
+        recusa('NOT_OBJECT');
+    const raiz = json;
+    // ── Rejeição RECONHECIDA ────────────────────────────────────────────────
+    //
+    // Antes de exigir o lote: uma rejeição legítima do ADN não traz lote nenhum,
+    // e cobrá-lo dela transformaria "seu cliente não teve nota" em "o contrato
+    // quebrou" — o alarme mais caro que este produto poderia dar.
+    const codigo = leiaCodigo(raiz[profile.codeField]);
+    if (codigo) {
+        const oficial = NFSE_ADN_OFFICIAL_CODES[codigo];
+        if (oficial?.outcome === 'no_documents') {
+            return {
+                documents: [],
+                // A posição de quem não achou nada é a de onde partiu. Ver o comentário
+                // de `fromNsu` acima: `null` aqui faria a próxima execução recomeçar.
+                lastNsu: fromNsu,
+                maxNsu: null,
+                // Esgotado: o Manual dos Municípios §1.4.2.b manda esperar uma hora
+                // "caso receba a indicação que não existem mais documentos".
+                exhausted: true,
+                providerStatus: codigo,
+            };
+        }
+        if (oficial) {
+            throw new FiscalProviderError(oficial.errorClass ?? 'unknown', `ADN recusou: ${oficial.meaning}`, codigo);
+        }
+        // Código do ADN que não está no nosso mapa. NÃO é lote vazio, e NÃO é
+        // `invalid`: o governo pode ter acrescentado um código sem mudar o
+        // envelope. `unknown` é tratado como transitório com teto pelo motor —
+        // errar para "tente de novo com espera" custa latência; errar para "está
+        // tudo bem, zero documentos" custa uma fiscalização.
+        throw new FiscalProviderError('unknown', 'ADN devolveu código não catalogado', codigo);
+    }
+    // ── Lote ────────────────────────────────────────────────────────────────
+    if (!(profile.batchField in raiz))
+        recusa('BATCH_FIELD_MISSING');
+    const lote = raiz[profile.batchField];
+    if (!Array.isArray(lote))
+        recusa('BATCH_NOT_ARRAY');
+    const itens = lote;
+    // O teto de 50 é oficial. Um lote maior significa que estamos falando com
+    // algo que não é o ADN — ou que o contrato mudou. Nos dois casos, parar.
+    if (itens.length > maxItens)
+        recusa('BATCH_OVER_OFFICIAL_LIMIT');
+    const documents = [];
+    let descompactadoNoLote = 0;
+    for (const item of itens) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item))
+            recusa('ITEM_NOT_OBJECT');
+        const linha = item;
+        const nsu = leiaNsu(linha[profile.itemNsuField]);
+        if (nsu === null)
+            recusa('ITEM_NSU_INVALID');
+        const conteudo = linha[profile.itemContentField];
+        if (typeof conteudo !== 'string' || conteudo.length === 0)
+            recusa('ITEM_CONTENT_MISSING');
+        if (!BASE64.test(conteudo))
+            recusa('ITEM_CONTENT_NOT_BASE64');
+        const bytes = Buffer.from(conteudo, 'base64');
+        let raw;
+        if (profile.contentEncoding === 'gzip+base64') {
+            // A verificação da assinatura vem ANTES da descompressão, e substitui o
+            // `try/catch` que virava fallback. Sem ela, "não é gzip" e "é gzip
+            // corrompido" chegam pelo mesmo caminho — e o antigo `catch` respondia
+            // aos dois tratando os bytes como XML.
+            if (bytes.length < 2 || bytes[0] !== GZIP_MAGIC[0] || bytes[1] !== GZIP_MAGIC[1]) {
+                recusa('ITEM_CONTENT_NOT_GZIP');
+            }
+            try {
+                // `maxOutputLength` é a defesa contra bomba de descompressão: o zlib
+                // aborta ao ultrapassar, em vez de alocar até o processo morrer.
+                raw = new Uint8Array(gunzipSync(bytes, { maxOutputLength: maxDoc }));
+            }
+            catch (err) {
+                // O zlib distingue os dois casos, e a distinção importa: "grande demais"
+                // é possivelmente hostil e "corrompido" é possivelmente rede.
+                const code = err?.code;
+                if (code === 'ERR_BUFFER_TOO_LARGE')
+                    recusa('ITEM_CONTENT_TOO_LARGE');
+                recusa('ITEM_CONTENT_DECOMPRESSION_FAILED');
+            }
+        }
+        else {
+            if (bytes.length > maxDoc)
+                recusa('ITEM_CONTENT_TOO_LARGE');
+            raw = new Uint8Array(bytes);
+        }
+        descompactadoNoLote += raw.byteLength;
+        // O teto do LOTE existe porque o produto dos tetos individuais não é um
+        // teto: 50 documentos de 8 MiB seriam 400 MiB perfeitamente "válidos".
+        if (descompactadoNoLote > maxLote)
+            recusa('BATCH_DECOMPRESSED_TOO_LARGE');
+        documents.push({ nsu, raw, mimeType: 'application/xml' });
+    }
+    const ultimo = leiaPosicao(raiz, profile.lastNsuField, recusa);
+    const maximo = leiaPosicao(raiz, profile.maxNsuField, recusa);
+    // Sem `ultNSU` declarado, a posição é a do último item — e, se nem item houve,
+    // é de onde partimos. Jamais `null`: ver o comentário de `fromNsu`.
+    const lastNsu = ultimo ?? documents.at(-1)?.nsu ?? fromNsu;
+    return {
+        documents,
+        lastNsu,
+        maxNsu: maximo,
+        // Esgotado é o servidor DECLARANDO que a posição alcançou o máximo
+        // (Manual dos Municípios §1.4.2.b: "Se o NSU informado (ultNSU) for igual ao
+        // maior NSU do Ambiente Nacional (maxNSU), então não existem mais
+        // documentos"). Nunca por lote vazio: um lote vazio no meio da faixa não
+        // autoriza a espera de uma hora, e tratá-lo assim atrasaria o cliente à toa.
+        exhausted: lastNsu !== null && maximo !== null && lastNsu === maximo,
+        providerStatus: null,
+    };
+}
+/**
+ * NSU como o contrato o define: dígitos, sem sinal, sem separador.
+ *
+ * Número JSON é aceito e normalizado para texto — o ADN pode enviá-lo como
+ * número, e recusá-lo seria rigor sem propósito. O que não é aceito é qualquer
+ * coisa que não seja uma posição: `null`, negativo, decimal, texto com letra.
+ * Um NSU que não é posição não pode governar cursor.
+ */
+function leiaNsu(v) {
+    if (typeof v === 'number') {
+        return Number.isSafeInteger(v) && v >= 0 ? String(v) : null;
+    }
+    if (typeof v === 'string' && /^\d{1,20}$/.test(v))
+        return v;
+    return null;
+}
+/** `ultNSU`/`maxNSU`: ausente é legítimo; presente e inválido, não. */
+function leiaPosicao(raiz, campo, recusa) {
+    if (!(campo in raiz))
+        return null;
+    const bruto = raiz[campo];
+    if (bruto === null || bruto === undefined)
+        return null;
+    const nsu = leiaNsu(bruto);
+    // Presente e ilegível é diferente de ausente: o primeiro é contrato quebrado,
+    // o segundo é campo opcional. Tratá-los igual perderia a quebra.
+    if (nsu === null)
+        recusa('NSU_POSITION_INVALID');
+    return nsu;
+}
+/** O código do ADN, quando a resposta é uma rejeição. `E` seguido de dígitos. */
+function leiaCodigo(v) {
+    if (typeof v !== 'string')
+        return null;
+    const t = v.trim().toUpperCase();
+    return /^E\d{4}$/.test(t) ? t : null;
+}
+//# sourceMappingURL=nfse-adn-envelope.js.map

package/dist/fiscal/contracts/nfse-adn-envelope.js.map

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

package/dist/fiscal/coverage/model.d.ts

@@ -0,0 +1,86 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalDocumentType } from '../ingestion/provider.js';
+/**
+ * Onde a coleta automática alcança — e, principalmente, onde não sabemos.
+ *
+ * ## A frase que um produto nacional diz sem perceber
+ *
+ * "O ADN cobre a NFS-e do Brasil inteiro." É falsa. A NFS-e nacional depende de
+ * ADESÃO do município ao convênio; quem não aderiu continua emitindo pelo portal
+ * próprio, com login próprio e nenhum NSU. Vender coleta automática para um
+ * cliente cuja prefeitura não aderiu é prometer trabalho que ninguém fará — e o
+ * escritório só descobre no fechamento, quando as notas não estão lá.
+ *
+ * ## Por que a herança é PROIBIDA de cima para baixo
+ *
+ * A tentação estrutural é: "não há linha para este município, use a nacional".
+ * Isso é exatamente como a afirmação falsa entra no sistema — uma linha correta
+ * sobre o ADN respondendo uma pergunta sobre Marechal Cândido Rondon.
+ *
+ * Aqui, uma pergunta MUNICIPAL só é respondida por uma linha municipal. Sem
+ * medição do município, a resposta é a linha municipal PADRÃO, que diz
+ * `UNKNOWN`. A linha nacional responde apenas perguntas de escopo nacional.
+ *
+ * ## Cobertura técnica não é validação legal
+ *
+ * Saber COLETAR um documento não diz nada sobre a regra fiscal que se aplica a
+ * ele. `fiscal_rule` continua com suas 17 regras e zero validadas por pessoa, e
+ * nada neste módulo mexe nesse número.
+ */
+export type CoverageStatus = 'SUPPORTED_OFFICIAL' | 'SUPPORTED_PROVIDER' | 'SUPPORTED_MANUAL_FALLBACK' | 'UNKNOWN' | 'UNSUPPORTED';
+export type CoverageScope = 'national' | 'state' | 'municipal';
+export interface FiscalCoverage {
+    id: string;
+    documentType: FiscalDocumentType;
+    jurisdictionScope: CoverageScope;
+    /** UF, código IBGE, ou `null` para a linha PADRÃO daquele escopo. */
+    jurisdictionCode: string | null;
+    provider: string;
+    coverageStatus: CoverageStatus;
+    automationMethod: string | null;
+    credentialRequirement: string;
+    environments: readonly string[];
+    fallbackType: string | null;
+    lastVerifiedAt: string | null;
+    sourceReference: string | null;
+    notes: string | null;
+}
+/** A resposta quando nem a linha padrão existe. Desconhecida, nunca coberta. */
+export declare function unknownCoverage(documentType: FiscalDocumentType, scope: CoverageScope, code: string | null): FiscalCoverage;
+/**
+ * Resolve a cobertura de uma pergunta específica.
+ *
+ * Duas etapas, e a segunda NUNCA sobe de escopo: a linha exata do código, e
+ * depois a linha padrão do MESMO escopo. Não há terceira etapa.
+ */
+export declare function resolveFiscalCoverage(tx: Tx, input: {
+    documentType: FiscalDocumentType;
+    jurisdictionScope: CoverageScope;
+    jurisdictionCode?: string | null;
+}): Promise<FiscalCoverage>;
+/**
+ * A cobertura que vale para um CLIENTE — a pergunta que a tela realmente faz.
+ *
+ * NFS-e é municipal por natureza: quem recolhe ISS é a prefeitura. Por isso a
+ * pergunta pelo cliente vai ao escopo municipal, e é ali que ela encontra
+ * `UNKNOWN` enquanto ninguém tiver medido a adesão daquele município. NF-e e
+ * CT-e são de distribuição nacional, e a pergunta é nacional.
+ */
+export declare function coverageForClient(tx: Tx, input: {
+    clientId: string;
+    documentType: FiscalDocumentType;
+}): Promise<FiscalCoverage & {
+    jurisdictionKnown: boolean;
+}>;
+/** O catálogo inteiro, para a tela de cobertura. */
+export declare function listFiscalCoverage(tx: Tx): Promise<FiscalCoverage[]>;
+/**
+ * Existe alguma afirmação de cobertura NACIONAL para NFS-e municipal?
+ *
+ * A pergunta parece estranha e é o oráculo de `UNIVERSAL_NFSE_COVERAGE_ASSUMED`:
+ * o modelo passa se, e somente se, uma pergunta municipal sem medição não
+ * devolver "coberto". Um teste que só verificasse a linha nacional passaria com
+ * o defeito presente.
+ */
+export declare function assumesUniversalNfseCoverage(tx: Tx): Promise<boolean>;
+//# sourceMappingURL=model.d.ts.map

package/dist/fiscal/coverage/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/fiscal/coverage/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,oBAAoB,GACpB,2BAA2B,GAC3B,SAAS,GACT,aAAa,CAAC;AAElB,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,OAAO,GAAG,WAAW,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,kBAAkB,CAAC;IACjC,iBAAiB,EAAE,aAAa,CAAC;IACjC,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,gFAAgF;AAChF,wBAAgB,eAAe,CAC7B,YAAY,EAAE,kBAAkB,EAChC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,cAAc,CAgBhB;AAsCD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,YAAY,EAAE,kBAAkB,CAAC;IACjC,iBAAiB,EAAE,aAAa,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,GACA,OAAO,CAAC,cAAc,CAAC,CAwBzB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,GAC5D,OAAO,CAAC,cAAc,GAAG;IAAE,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAoB1D;AAED,oDAAoD;AACpD,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAM1E;AAED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAAC,EAAE,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ3E"}

package/dist/fiscal/coverage/model.js

@@ -0,0 +1,120 @@
+import { loadClientJurisdiction } from '../repository.js';
+/** A resposta quando nem a linha padrão existe. Desconhecida, nunca coberta. */
+export function unknownCoverage(documentType, scope, code) {
+    return {
+        id: 'unknown',
+        documentType,
+        jurisdictionScope: scope,
+        jurisdictionCode: code,
+        provider: 'desconhecido',
+        coverageStatus: 'UNKNOWN',
+        automationMethod: null,
+        credentialRequirement: 'unknown',
+        environments: [],
+        fallbackType: 'manual_upload',
+        lastVerifiedAt: null,
+        sourceReference: null,
+        notes: 'Nenhuma linha de cobertura para esta combinação. Ninguém mediu.',
+    };
+}
+const map = (r) => ({
+    id: r.id,
+    documentType: r.document_type,
+    jurisdictionScope: r.jurisdiction_scope,
+    jurisdictionCode: r.jurisdiction_code,
+    provider: r.provider,
+    coverageStatus: r.coverage_status,
+    automationMethod: r.automation_method,
+    credentialRequirement: r.credential_requirement,
+    environments: r.environments ?? [],
+    fallbackType: r.fallback_type,
+    lastVerifiedAt: r.last_verified_at ? r.last_verified_at.toISOString().slice(0, 10) : null,
+    sourceReference: r.source_reference,
+    notes: r.notes,
+});
+const COLUMNS = `id, document_type, jurisdiction_scope, jurisdiction_code, provider,
+                 coverage_status, automation_method, credential_requirement, environments,
+                 fallback_type, last_verified_at, source_reference, notes`;
+/**
+ * Resolve a cobertura de uma pergunta específica.
+ *
+ * Duas etapas, e a segunda NUNCA sobe de escopo: a linha exata do código, e
+ * depois a linha padrão do MESMO escopo. Não há terceira etapa.
+ */
+export async function resolveFiscalCoverage(tx, input) {
+    const code = input.jurisdictionCode ?? null;
+    if (code) {
+        const exact = await tx `
+      SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+       WHERE document_type = ${input.documentType}
+         AND jurisdiction_scope = ${input.jurisdictionScope}
+         AND jurisdiction_code = ${code}
+       LIMIT 1
+    `;
+        if (exact[0])
+            return map(exact[0]);
+    }
+    const fallback = await tx `
+    SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+     WHERE document_type = ${input.documentType}
+       AND jurisdiction_scope = ${input.jurisdictionScope}
+       AND jurisdiction_code IS NULL
+     LIMIT 1
+  `;
+    if (fallback[0])
+        return { ...map(fallback[0]), jurisdictionCode: code };
+    return unknownCoverage(input.documentType, input.jurisdictionScope, code);
+}
+/**
+ * A cobertura que vale para um CLIENTE — a pergunta que a tela realmente faz.
+ *
+ * NFS-e é municipal por natureza: quem recolhe ISS é a prefeitura. Por isso a
+ * pergunta pelo cliente vai ao escopo municipal, e é ali que ela encontra
+ * `UNKNOWN` enquanto ninguém tiver medido a adesão daquele município. NF-e e
+ * CT-e são de distribuição nacional, e a pergunta é nacional.
+ */
+export async function coverageForClient(tx, input) {
+    const jurisdiction = await loadClientJurisdiction(tx, input.clientId);
+    if (input.documentType === 'nfse') {
+        const coverage = await resolveFiscalCoverage(tx, {
+            documentType: 'nfse',
+            jurisdictionScope: 'municipal',
+            jurisdictionCode: jurisdiction.cityIbge,
+        });
+        // Sem o IBGE do cliente não dá para nem PERGUNTAR pelo município certo. É um
+        // dado que falta, e dizer isso é diferente de dizer que não há cobertura.
+        return { ...coverage, jurisdictionKnown: jurisdiction.cityIbge !== null };
+    }
+    const coverage = await resolveFiscalCoverage(tx, {
+        documentType: input.documentType,
+        jurisdictionScope: 'national',
+        jurisdictionCode: null,
+    });
+    return { ...coverage, jurisdictionKnown: true };
+}
+/** O catálogo inteiro, para a tela de cobertura. */
+export async function listFiscalCoverage(tx) {
+    const rows = await tx `
+    SELECT ${tx.unsafe(COLUMNS)} FROM fiscal_coverage
+     ORDER BY document_type, jurisdiction_scope, jurisdiction_code NULLS FIRST
+  `;
+    return rows.map(map);
+}
+/**
+ * Existe alguma afirmação de cobertura NACIONAL para NFS-e municipal?
+ *
+ * A pergunta parece estranha e é o oráculo de `UNIVERSAL_NFSE_COVERAGE_ASSUMED`:
+ * o modelo passa se, e somente se, uma pergunta municipal sem medição não
+ * devolver "coberto". Um teste que só verificasse a linha nacional passaria com
+ * o defeito presente.
+ */
+export async function assumesUniversalNfseCoverage(tx) {
+    const resolved = await resolveFiscalCoverage(tx, {
+        documentType: 'nfse',
+        jurisdictionScope: 'municipal',
+        // Um IBGE que ninguém mediu. É o caso da esmagadora maioria dos 5.570.
+        jurisdictionCode: '9999999',
+    });
+    return resolved.coverageStatus !== 'UNKNOWN';
+}
+//# sourceMappingURL=model.js.map

package/dist/fiscal/coverage/model.js.map

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

package/dist/fiscal/coverage/requests.d.ts

@@ -0,0 +1,70 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalDocumentType } from '../ingestion/provider.js';
+/**
+ * A ponte entre a coleta automática e a solicitação "Documentos fiscais do mês".
+ *
+ * ## A tentação, e por que ela está errada
+ *
+ * O caminho óbvio: chegou nota do cliente na competência ⇒ marque
+ * `docs_fiscais_mes` como concluída. Ele é errado por três motivos independentes,
+ * e qualquer um bastaria:
+ *
+ *  1. **Uma nota não é as notas.** O ADN traz o que o município publicou; a
+ *     entrada de mercadoria do cliente pode nunca aparecer ali. Fechar a
+ *     solicitação com uma nota de saída faz o escritório parar de perguntar
+ *     pelas de entrada.
+ *  2. **A cobertura pode ser desconhecida.** Se a prefeitura não aderiu ao ADN,
+ *     a automação nunca trará nada — e fechar por ausência seria pior ainda.
+ *  3. **Concluir é ato de quem confere.** A solicitação existe porque alguém
+ *     precisa OLHAR o conjunto. Um robô que a fecha remove a conferência sem
+ *     substituí-la.
+ *
+ * Por isso este módulo **não escreve nada**. Ele CLASSIFICA, e a classificação
+ * aparece ao lado da solicitação para que a pessoa decida com mais informação —
+ * que é o oposto de decidir por ela.
+ */
+export type RequestCoverageLevel = 'NOT_COVERED' | 'PARTIALLY_COVERED' | 'FULLY_COVERED_BY_AUTOMATION';
+export interface RequestCoverageAssessment {
+    clientId: string;
+    competenceLabel: string;
+    level: RequestCoverageLevel;
+    /** Documentos coletados automaticamente naquela competência. */
+    automaticDocuments: number;
+    /** Direções presentes. Só saída é sinal de cobertura parcial, não total. */
+    directions: readonly string[];
+    coverageStatus: string;
+    /** Nunca é verdadeiro nesta fase. O campo existe para tornar isso auditável. */
+    autoClosed: false;
+    detail: string;
+}
+/**
+ * Classifica a cobertura da solicitação de uma competência.
+ *
+ * `FULLY_COVERED_BY_AUTOMATION` exige as DUAS condições, e não uma:
+ * cobertura oficial declarada para a jurisdição E documentos de entrada e saída
+ * presentes. Com só uma delas, o máximo é `PARTIALLY_COVERED` — porque só uma
+ * delas é, literalmente, cobertura parcial.
+ */
+export declare function assessRequestCoverage(tx: Tx, input: {
+    clientId: string;
+    competenceLabel: string;
+    documentType?: FiscalDocumentType;
+}): Promise<RequestCoverageAssessment>;
+export interface RequestCoverageRow extends RequestCoverageAssessment {
+    requestId: string;
+    clientName: string | null;
+    status: string;
+    dueDate: string | null;
+}
+/**
+ * As solicitações de "Documentos fiscais do mês" com sua classificação.
+ *
+ * Leitura pura. Nenhuma linha de `recurring_instance` é tocada — e um teste
+ * confere isso comparando o `updated_at` das solicitações antes e depois, porque
+ * "eu não escrevi nada" é uma afirmação que precisa de oráculo.
+ */
+export declare function listRequestCoverage(tx: Tx, input?: {
+    competenceLabel?: string;
+    limit?: number;
+}): Promise<RequestCoverageRow[]>;
+//# sourceMappingURL=requests.d.ts.map

package/dist/fiscal/coverage/requests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../../src/fiscal/coverage/requests.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,aAAa,GACb,mBAAmB,GACnB,6BAA6B,CAAC;AAElC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,gEAAgE;IAChE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,UAAU,EAAE,KAAK,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,GACA,OAAO,CAAC,yBAAyB,CAAC,CAuDpC;AAED,MAAM,WAAW,kBAAmB,SAAQ,yBAAyB;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,EAAE,EACN,KAAK,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACvD,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwC/B"}

package/dist/fiscal/coverage/requests.js

@@ -0,0 +1,95 @@
+/**
+ * Classifica a cobertura da solicitação de uma competência.
+ *
+ * `FULLY_COVERED_BY_AUTOMATION` exige as DUAS condições, e não uma:
+ * cobertura oficial declarada para a jurisdição E documentos de entrada e saída
+ * presentes. Com só uma delas, o máximo é `PARTIALLY_COVERED` — porque só uma
+ * delas é, literalmente, cobertura parcial.
+ */
+export async function assessRequestCoverage(tx, input) {
+    const documentType = input.documentType ?? 'nfse';
+    const [doc] = await tx `
+    SELECT count(*)::int                                   AS total,
+           coalesce(array_agg(DISTINCT direction), '{}')   AS direcoes
+      FROM fiscal_document
+     WHERE client_id = ${input.clientId}
+       AND competence_label = ${input.competenceLabel}
+       AND source <> 'manual'
+  `;
+    const [cov] = await tx `
+    SELECT fc.coverage_status
+      FROM client c
+      LEFT JOIN fiscal_coverage fc
+        ON 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)
+     WHERE c.id = ${input.clientId}
+     ORDER BY fc.jurisdiction_code NULLS LAST
+     LIMIT 1
+  `;
+    const coverageStatus = cov?.coverage_status ?? 'UNKNOWN';
+    const total = doc?.total ?? 0;
+    const direcoes = doc?.direcoes ?? [];
+    const oficial = coverageStatus === 'SUPPORTED_OFFICIAL' || coverageStatus === 'SUPPORTED_PROVIDER';
+    const temEntradaESaida = direcoes.includes('received') && direcoes.includes('issued');
+    const level = total === 0
+        ? 'NOT_COVERED'
+        : oficial && temEntradaESaida
+            ? 'FULLY_COVERED_BY_AUTOMATION'
+            : 'PARTIALLY_COVERED';
+    return {
+        clientId: input.clientId,
+        competenceLabel: input.competenceLabel,
+        level,
+        automaticDocuments: total,
+        directions: direcoes,
+        coverageStatus,
+        autoClosed: false,
+        detail: level === 'NOT_COVERED'
+            ? 'Nenhum documento coletado automaticamente nesta competência.'
+            : level === 'FULLY_COVERED_BY_AUTOMATION'
+                ? `${total} documentos coletados, com entrada e saída, em jurisdição com cobertura oficial.`
+                : oficial
+                    ? `${total} documentos coletados, mas falta ${direcoes.includes('issued') ? 'documento de entrada' : 'documento de saída'}.`
+                    : `${total} documentos coletados, porém a cobertura desta jurisdição é ${coverageStatus}.`,
+    };
+}
+/**
+ * As solicitações de "Documentos fiscais do mês" com sua classificação.
+ *
+ * Leitura pura. Nenhuma linha de `recurring_instance` é tocada — e um teste
+ * confere isso comparando o `updated_at` das solicitações antes e depois, porque
+ * "eu não escrevi nada" é uma afirmação que precisa de oráculo.
+ */
+export async function listRequestCoverage(tx, input = {}) {
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+    const rows = await tx `
+    SELECT ri.id AS request_id, ri.client_id, c.display_name AS client_name,
+           ri.status, ri.due_date, comp.label AS competence_label
+      FROM recurring_instance ri
+      JOIN recurring_item_type rit ON rit.id = ri.item_type_id
+      JOIN competence comp ON comp.id = ri.competence_id
+      JOIN client c ON c.id = ri.client_id
+     WHERE rit.key = 'docs_fiscais_mes'
+       AND ri.deleted_at IS NULL
+       AND ${input.competenceLabel ? tx `comp.label = ${input.competenceLabel}` : tx `true`}
+     ORDER BY comp.label DESC, c.display_name
+     LIMIT ${limit}
+  `;
+    const out = [];
+    for (const r of rows) {
+        const assessment = await assessRequestCoverage(tx, {
+            clientId: r.client_id,
+            competenceLabel: r.competence_label,
+        });
+        out.push({
+            ...assessment,
+            requestId: r.request_id,
+            clientName: r.client_name,
+            status: r.status,
+            dueDate: r.due_date ? r.due_date.toISOString().slice(0, 10) : null,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=requests.js.map

package/dist/fiscal/coverage/requests.js.map

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