@baruk/core 0.4.2 → 0.6.0

package/dist/fiscal/collection/competence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"competence.d.ts","sourceRoot":"","sources":["../../../src/fiscal/collection/competence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC;AAED,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAG,yBAAkC,CAAC;AAE5E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAgB1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,GAAG,gBAAgB,CAItE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,IAAI,CAYN"}

package/dist/fiscal/collection/competence.js

@@ -0,0 +1,90 @@
+/**
+ * A janela da coleta — dita por extenso, nunca deduzida.
+ *
+ * ## O relato que originou este módulo
+ *
+ * A equipe do escritório chama de "dar baixa nas notas" o trabalho de, na virada
+ * do mês, entrar nos portais e recolher os documentos do período. Ao descrever
+ * esse trabalho, o relato humano trouxe exemplos de datas que não fechavam entre
+ * si — o que é absolutamente normal em conversa, e absolutamente perigoso como
+ * fonte de regra.
+ *
+ * A tentação é transformar "mês anterior" em constante. O erro que isso produz é
+ * silencioso: uma coleta rodada em 01/11 sobre uma janela que ninguém confirmou
+ * traz documentos de um período que não é o que a pessoa tinha em mente, e a
+ * ausência do que faltava só aparece no fechamento.
+ *
+ * Aqui a competência é um par ano/mês, e o período é um par de DATAS derivado
+ * dele. A sugestão padrão existe — mês calendário anterior —, mas ela é uma
+ * SUGESTÃO exibida, não um valor implícito: a tela mostra "serão consultados
+ * documentos de DD/MM/AAAA a DD/MM/AAAA" antes de qualquer execução, e as duas
+ * datas são gravadas na autorização.
+ */
+export class InvalidCompetenceError extends Error {
+    detail;
+    constructor(detail) {
+        super(`competência inválida: ${detail}`);
+        this.detail = detail;
+        this.name = 'InvalidCompetenceError';
+    }
+}
+/** A política padrão desta fase, nomeada para poder ser citada e mudada. */
+export const DEFAULT_COMPETENCE_POLICY = 'PREVIOUS_CALENDAR_MONTH';
+/**
+ * A competência de um par ano/mês.
+ *
+ * O último dia sai do calendário: `Date.UTC(ano, mês, 0)` — com o mês em base 1
+ * — devolve o último dia daquele mês. Fevereiro bissexto sai de graça, que é o
+ * ponto de não escrever `30`.
+ */
+export function competenceOf(year, month) {
+    if (!Number.isInteger(year) || year < 2000 || year > 2100) {
+        throw new InvalidCompetenceError('ano fora de 2000–2100');
+    }
+    if (!Number.isInteger(month) || month < 1 || month > 12) {
+        throw new InvalidCompetenceError('mês fora de 1–12');
+    }
+    const mm = String(month).padStart(2, '0');
+    const lastDay = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    return {
+        year,
+        month,
+        label: `${year}-${mm}`,
+        periodStart: `${year}-${mm}-01`,
+        periodEnd: `${year}-${mm}-${String(lastDay).padStart(2, '0')}`,
+    };
+}
+/**
+ * A SUGESTÃO padrão para uma execução feita em `reference`: o mês calendário
+ * anterior.
+ *
+ * Chama-se `suggest` e não `default` de propósito. Uma função chamada
+ * `defaultCompetence()` acaba sendo usada como valor efetivo por quem não leu;
+ * `suggestCompetenceFor()` obriga quem chama a decidir o que fazer com a
+ * sugestão — que é exibi-la ao lado das duas datas.
+ */
+export function suggestCompetenceFor(reference) {
+    const year = reference.getUTCFullYear();
+    const month = reference.getUTCMonth() + 1; // base 1
+    return month === 1 ? competenceOf(year - 1, 12) : competenceOf(year, month - 1);
+}
+/**
+ * Confere uma janela informada à mão contra a competência declarada.
+ *
+ * Permitir janela manual e conferi-la não são opostos: o operador pode querer um
+ * recorte menor dentro do mês — o que é legítimo —, mas uma janela que atravessa
+ * a competência declarada significa que um dos dois campos está errado, e gravar
+ * os dois deixaria a autorização dizendo duas coisas.
+ */
+export function validateWindow(competence, periodStart, periodEnd) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(periodStart) || !/^\d{4}-\d{2}-\d{2}$/.test(periodEnd)) {
+        throw new InvalidCompetenceError('datas devem estar em YYYY-MM-DD');
+    }
+    if (periodEnd < periodStart) {
+        throw new InvalidCompetenceError('data final anterior à inicial');
+    }
+    if (periodStart < competence.periodStart || periodEnd > competence.periodEnd) {
+        throw new InvalidCompetenceError(`janela ${periodStart}..${periodEnd} sai da competência ${competence.label}`);
+    }
+}
+//# sourceMappingURL=competence.js.map

package/dist/fiscal/collection/competence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"competence.js","sourceRoot":"","sources":["../../../src/fiscal/collection/competence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAaH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC1B;IAArB,YAAqB,MAAc;QACjC,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;QADtB,WAAM,GAAN,MAAM,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAAG,yBAAkC,CAAC;AAE5E;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,KAAa;IACtD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;QAC1D,MAAM,IAAI,sBAAsB,CAAC,uBAAuB,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,sBAAsB,CAAC,kBAAkB,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAChE,OAAO;QACL,IAAI;QACJ,KAAK;QACL,KAAK,EAAE,GAAG,IAAI,IAAI,EAAE,EAAE;QACtB,WAAW,EAAE,GAAG,IAAI,IAAI,EAAE,KAAK;QAC/B,SAAS,EAAE,GAAG,IAAI,IAAI,EAAE,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;KAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAe;IAClD,MAAM,IAAI,GAAG,SAAS,CAAC,cAAc,EAAE,CAAC;IACxC,MAAM,KAAK,GAAG,SAAS,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,CAAC,SAAS;IACpD,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,UAA4B,EAC5B,WAAmB,EACnB,SAAiB;IAEjB,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,sBAAsB,CAAC,iCAAiC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,SAAS,GAAG,WAAW,EAAE,CAAC;QAC5B,MAAM,IAAI,sBAAsB,CAAC,+BAA+B,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,WAAW,GAAG,UAAU,CAAC,WAAW,IAAI,SAAS,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;QAC7E,MAAM,IAAI,sBAAsB,CAC9B,UAAU,WAAW,KAAK,SAAS,uBAAuB,UAAU,CAAC,KAAK,EAAE,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/fiscal/collection/first-contact.d.ts

@@ -0,0 +1,103 @@
+import type { Tx } from '../../db/client.js';
+import { type FiscalEnvironment } from '../eligibility.js';
+import { type FiscalRunAuthorization } from './authorization.js';
+/**
+ * O PRIMEIRO CONTATO — a execução única que existe para obter o aceite remoto.
+ *
+ * ## O impasse que ele desfaz
+ *
+ * Toda execução exigia `verified_at`. `verified_at` significa "o ambiente
+ * oficial já aceitou este material". E só uma execução produz esse aceite. O
+ * ciclo se fechava sobre si mesmo, e a primeira consulta real de qualquer
+ * cliente era inalcançável por construção — não por configuração, não por falta
+ * de certificado.
+ *
+ * A saída não é afrouxar o portão do worker: é reconhecer que existem DUAS
+ * perguntas, e que só uma delas o cron pode responder sozinho.
+ *
+ *   validação LOCAL       o arquivo abre, a chave casa, o titular confere, as
+ *                         datas valem. Custa milissegundos, não toca a rede, e
+ *                         acontece no segundo do upload.
+ *   verificação REMOTA    aquele ambiente aceitou aquele material. Custa uma
+ *                         requisição autenticada em nome de um terceiro — e, se
+ *                         feita fora de hora, custa ao CLIENTE um CNPJ bloqueado
+ *                         por consumo indevido.
+ *
+ * O primeiro contato é o ato que atravessa a segunda pela primeira vez. Por
+ * isso ele é manual, único, somente leitura, e assinado por uma pessoa que
+ * declarou o responsável contábil.
+ *
+ * ## Por que o cron jamais chega aqui
+ *
+ * Não por um `if` neste arquivo — por CHECK no banco (0062): uma autorização
+ * com `first_contact = true` e `trigger_kind = 'scheduled'` viola a constraint
+ * e a transação morre. Um refactor deste módulo não consegue reabrir a porta.
+ *
+ * ## O que este módulo NÃO faz
+ *
+ * Não fala com serviço fiscal nenhum. Ele decide, reivindica e registra; quem
+ * fala é o adaptador que lhe é passado. Nesta frente, todo adaptador em uso é
+ * sintético — e os portões `connectorImplemented`, `protocolVerified` e o
+ * transporte real continuam fechados por conta própria.
+ */
+/** Por que o primeiro contato foi recusado. Vocabulário fechado. */
+export type FirstContactRefusal = 'authorization_not_found' | 'authorization_not_first_contact' | 'authorization_expired' | 'authorization_revoked' | 'authorization_already_consumed' | 'authorization_scheduled_trigger' | 'tenant_mismatch' | 'client_mismatch' | 'connector_mismatch' | 'competence_mismatch' | 'credential_fingerprint_mismatch' | 'credential_not_local_valid' | 'credential_already_verified' | 'client_not_enrolled' | 'tenant_automation_disabled' | 'connector_not_implemented' | 'protocol_not_verified' | 'real_transport_disabled' | 'claim_lost';
+export type FirstContactOutcome = {
+    status: 'refused';
+    reason: FirstContactRefusal;
+    detail: string;
+} | {
+    status: 'executed';
+    runId: string;
+    authorization: FiscalRunAuthorization;
+    /** O ambiente aceitou o material? Só `true` grava a verificação remota. */
+    remoteVerified: boolean;
+    documentCount: number;
+};
+/**
+ * O que o adaptador precisa devolver para que o aceite remoto seja gravado.
+ *
+ * `accepted` não é "respondeu 200". É "a resposta foi reconhecida como do
+ * contrato deste provedor" — um 200 com corpo de página de erro, um redirect
+ * para portal de login, um HTML de manutenção: todos são 200, e nenhum deles
+ * prova que o certificado foi aceito.
+ */
+export interface FirstContactProbe {
+    accepted: boolean;
+    /** Classe da recusa, quando houve. NUNCA a mensagem do provedor. */
+    failureCode?: string | null;
+    documentCount?: number;
+    /** Metadados de cursor seguros para trilha (NSU, etc). Sem conteúdo fiscal. */
+    cursor?: Record<string, string | number | null>;
+}
+export interface FirstContactInput {
+    authorizationId: string;
+    tenantId: string;
+    clientId: string;
+    connector: string;
+    environment: FiscalEnvironment;
+    competenceYear: number;
+    competenceMonth: number;
+    actorId: string;
+    /**
+     * Fala com o provedor. Só é chamado depois de TODOS os portões e depois de a
+     * autorização ter sido reivindicada — nunca antes.
+     */
+    probe: () => Promise<FirstContactProbe>;
+    /**
+     * O transporte real está habilitado para este conector? Vem de fora porque a
+     * flag mora no adaptador, e este módulo não deve conhecer nenhum.
+     */
+    realTransportEnabled: boolean;
+    now?: Date;
+}
+/**
+ * Executa o primeiro contato — ou recusa, dizendo exatamente por quê.
+ *
+ * A ordem dos portões é deliberada e vai do mais barato ao mais caro, com uma
+ * regra acima de tudo: **nada que toque credencial ou rede acontece antes de
+ * todos os portões de papel terem passado**. Um portão que fechasse depois de o
+ * cofre ter sido aberto já teria custado o que se queria evitar.
+ */
+export declare function runFirstContact(tx: Tx, input: FirstContactInput): Promise<FirstContactOutcome>;
+//# sourceMappingURL=first-contact.d.ts.map

package/dist/fiscal/collection/first-contact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-contact.d.ts","sourceRoot":"","sources":["../../../src/fiscal/collection/first-contact.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAI7C,OAAO,EAA6B,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtF,OAAO,EAA2B,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,oEAAoE;AACpE,MAAM,MAAM,mBAAmB,GAC3B,yBAAyB,GACzB,iCAAiC,GACjC,uBAAuB,GACvB,uBAAuB,GACvB,gCAAgC,GAChC,iCAAiC,GACjC,iBAAiB,GACjB,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,iCAAiC,GACjC,4BAA4B,GAC5B,6BAA6B,GAC7B,qBAAqB,GACrB,4BAA4B,GAC5B,2BAA2B,GAC3B,uBAAuB,GACvB,yBAAyB,GACzB,YAAY,CAAC;AAEjB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClE;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,sBAAsB,CAAC;IACtC,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEN;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxC;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAQD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAgN9B"}

package/dist/fiscal/collection/first-contact.js

@@ -0,0 +1,201 @@
+import { uuidv7 } from '@baruk/shared';
+import { appendAudit } from '../../audit/audit.js';
+import { coverageForClient } from '../coverage/model.js';
+import { readFiscalCredentialReadiness } from '../credentials/readiness.js';
+import { evaluateFiscalEligibility } from '../eligibility.js';
+import { consumeRunAuthorization } from './authorization.js';
+const recusa = (reason, detail) => ({
+    status: 'refused',
+    reason,
+    detail,
+});
+/**
+ * Executa o primeiro contato — ou recusa, dizendo exatamente por quê.
+ *
+ * A ordem dos portões é deliberada e vai do mais barato ao mais caro, com uma
+ * regra acima de tudo: **nada que toque credencial ou rede acontece antes de
+ * todos os portões de papel terem passado**. Um portão que fechasse depois de o
+ * cofre ter sido aberto já teria custado o que se queria evitar.
+ */
+export async function runFirstContact(tx, input) {
+    const now = input.now ?? new Date();
+    // ═══ 1 · A autorização existe, e é DESTE escopo ═════════════════════════
+    const [auth] = await tx `
+    SELECT id, tenant_id, client_id, source, environment, competence_year, competence_month,
+           operation, first_contact, trigger_kind, credential_fingerprint,
+           expires_at, consumed_at, revoked_at
+      FROM fiscal_run_authorization
+     WHERE id = ${input.authorizationId}
+  `;
+    if (!auth)
+        return recusa('authorization_not_found', 'autorização inexistente');
+    // Cada binding é conferido em separado, e a recusa NOMEIA qual falhou. Um
+    // "não autorizado" genérico faria toda investigação começar do zero.
+    if (auth.tenant_id !== input.tenantId) {
+        return recusa('tenant_mismatch', 'autorização é de outra organização');
+    }
+    if (auth.client_id !== input.clientId) {
+        return recusa('client_mismatch', 'autorização é de outro cliente');
+    }
+    if (auth.source !== input.connector) {
+        return recusa('connector_mismatch', `autorização é do conector ${auth.source}`);
+    }
+    if (auth.competence_year !== input.competenceYear ||
+        auth.competence_month !== input.competenceMonth) {
+        return recusa('competence_mismatch', 'autorização é de outra competência');
+    }
+    if (!auth.first_contact) {
+        return recusa('authorization_not_first_contact', 'esta autorização não declara primeiro contato');
+    }
+    if (auth.trigger_kind !== 'manual') {
+        return recusa('authorization_scheduled_trigger', 'primeiro contato não aceita agendamento');
+    }
+    if (auth.revoked_at)
+        return recusa('authorization_revoked', 'autorização revogada');
+    if (auth.consumed_at)
+        return recusa('authorization_already_consumed', 'autorização já consumida');
+    if (auth.expires_at <= now)
+        return recusa('authorization_expired', 'autorização expirada');
+    // ═══ 2 · O escritório e o cliente disseram sim ══════════════════════════
+    //
+    // A elegibilidade é default-deny e cobre habilitação do tenant e matrícula do
+    // cliente. Ela é consultada AQUI, e não confiada à tela: a tela é uma
+    // conveniência, o portão é isto.
+    const eligibility = await evaluateFiscalEligibility(tx, {
+        clientId: input.clientId,
+        documentType: documentTypeOf(input.connector),
+        environment: input.environment,
+    });
+    if (!eligibility.eligible) {
+        const razoes = new Set(eligibility.reasons);
+        if (razoes.has('client_not_enrolled')) {
+            return recusa('client_not_enrolled', 'cliente sem matrícula fiscal para este documento');
+        }
+        if (razoes.has('tenant_automation_disabled') || razoes.has('environment_mismatch')) {
+            return recusa('tenant_automation_disabled', 'organização sem automação fiscal habilitada');
+        }
+        // `credential_not_ready` é ESPERADO aqui — o primeiro contato existe
+        // justamente para o caso em que a credencial ainda não foi aceita. Só ele
+        // é tolerado; qualquer outro motivo continua fechando.
+        const outros = [...razoes].filter((r) => r !== 'credential_not_ready' && r !== 'real_operation_not_declared');
+        if (outros.length > 0) {
+            return recusa('client_not_enrolled', `inelegível: ${outros.join(', ')}`);
+        }
+    }
+    // ═══ 3 · O conector existe DE VERDADE ══════════════════════════════════
+    //
+    // Aqui mora a correção da leitura que a C2 encontrou: cobertura oficial é
+    // fato do mundo; adaptador implementado é fato do repositório. Autorizar
+    // contra um conector inexistente falharia adiante com um erro de sistema, e a
+    // tela culparia o certificado.
+    const coverage = await coverageForClient(tx, {
+        clientId: input.clientId,
+        documentType: documentTypeOf(input.connector),
+    });
+    if (!coverage.connectorImplemented) {
+        return recusa('connector_not_implemented', 'este conector ainda não existe no produto');
+    }
+    if (!coverage.protocolVerified) {
+        return recusa('protocol_not_verified', 'o contrato do provedor não foi conferido');
+    }
+    if (!input.realTransportEnabled) {
+        return recusa('real_transport_disabled', 'transporte real desabilitado para este conector');
+    }
+    // ═══ 4 · A credencial: local válida, e ainda não aceita ═════════════════
+    const credential = await readFiscalCredentialReadiness(tx, {
+        clientId: input.clientId,
+        environment: input.environment,
+        source: input.connector,
+    });
+    if (credential.state === 'READY') {
+        // Já aceita: não há primeiro contato a fazer, e insistir gastaria uma
+        // requisição autenticada para descobrir o que já se sabe.
+        return recusa('credential_already_verified', 'esta credencial já foi aceita pelo ambiente');
+    }
+    if (!credential.eligibleForFirstContact) {
+        return recusa('credential_not_local_valid', `credencial em estado ${credential.state}`);
+    }
+    // O material aprovado é o material que vai. Trocar o certificado depois de
+    // autorizar invalida a autorização — quem assinou aprovou UM arquivo.
+    if (auth.credential_fingerprint && auth.credential_fingerprint !== credential.fingerprint) {
+        return recusa('credential_fingerprint_mismatch', 'o certificado mudou depois desta autorização');
+    }
+    // ═══ 5 · A reivindicação — e o banco decide quem ganha ══════════════════
+    //
+    // O `UPDATE ... WHERE consumed_at IS NULL` de `consumeRunAuthorization` é o
+    // que torna a execução única sob concorrência. Dois processos chegando juntos
+    // aqui: um recebe a linha, o outro recebe `null`. Nenhum `if` em TypeScript
+    // consegue essa garantia.
+    const runId = uuidv7();
+    const claimed = await consumeRunAuthorization(tx, {
+        authorizationId: input.authorizationId,
+        runId,
+    });
+    if (!claimed) {
+        return recusa('claim_lost', 'outra execução reivindicou esta autorização primeiro');
+    }
+    // ═══ 6 · Só agora se fala com o provedor ═══════════════════════════════
+    let probe;
+    try {
+        probe = await input.probe();
+    }
+    catch {
+        // Exceção do transporte não atravessa: a mensagem de um cliente HTTP cita a
+        // URL, e URL de provedor carrega credencial.
+        probe = { accepted: false, failureCode: 'transport' };
+    }
+    // O registro do desfecho.
+    //
+    // `CASE` em vez de montar SQL condicional: um fragmento interpolado no meio
+    // de um `SET` é o tipo de construção que funciona no teste e produz sintaxe
+    // inválida no primeiro campo a mais.
+    //
+    // E a tentativa é registrada nos DOIS desfechos — "tentou e o ambiente
+    // recusou" e "nunca tentou" pedem coisas opostas de quem opera, e sem esta
+    // coluna eram indistinguíveis.
+    const falha = probe.accepted ? null : (probe.failureCode ?? 'unknown');
+    await tx `
+    UPDATE digital_certificate
+       SET remote_verification_last_attempt_at = ${now},
+           last_verification_error = ${falha},
+           verified_at = CASE WHEN ${probe.accepted} THEN ${now} ELSE verified_at END,
+           verified_by = CASE WHEN ${probe.accepted} THEN ${input.actorId}::uuid ELSE verified_by END,
+           remote_verification_provider =
+             CASE WHEN ${probe.accepted} THEN ${input.connector} ELSE remote_verification_provider END,
+           updated_at = now()
+     WHERE client_id = ${input.clientId}
+       AND deleted_at IS NULL
+       AND local_validated_at IS NOT NULL
+       -- O certificado EXATO que foi aprovado. Sem isto, um cliente com dois
+       -- certificados teria os dois marcados por uma execução que usou um só.
+       AND (${credential.fingerprint}::text IS NULL OR fingerprint_sha256 = ${credential.fingerprint})
+  `;
+    await appendAudit(tx, {
+        actorId: input.actorId,
+        action: probe.accepted ? 'fiscal_first_contact_accepted' : 'fiscal_first_contact_refused',
+        resourceType: 'fiscal_run_authorization',
+        resourceId: input.authorizationId,
+        metadata: {
+            runId,
+            connector: input.connector,
+            environment: input.environment,
+            competence: `${input.competenceYear}-${String(input.competenceMonth).padStart(2, '0')}`,
+            documentCount: probe.documentCount ?? 0,
+            // Classe, nunca mensagem. E nenhum conteúdo fiscal.
+            failureCode: probe.accepted ? null : (probe.failureCode ?? 'unknown'),
+            cursor: probe.cursor ?? null,
+        },
+    });
+    return {
+        status: 'executed',
+        runId,
+        authorization: claimed,
+        remoteVerified: probe.accepted,
+        documentCount: probe.documentCount ?? 0,
+    };
+}
+/** O tipo de documento que um conector atende. */
+function documentTypeOf(connector) {
+    return connector === 'nfse_adn' ? 'nfse' : 'nfe';
+}
+//# sourceMappingURL=first-contact.js.map

package/dist/fiscal/collection/first-contact.js.map

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

package/dist/fiscal/collection/plan.d.ts

@@ -0,0 +1,74 @@
+import type { Tx } from '../../db/client.js';
+import { type FiscalCoverage } from '../coverage/model.js';
+import type { FiscalDocumentType, FiscalEnvironment } from '../eligibility.js';
+import { type FiscalCompetence } from './competence.js';
+import { type FiscalRunAuthorization } from './authorization.js';
+/**
+ * O plano de coleta de uma competência — CALCULADO, não guardado.
+ *
+ * ## Por que não existe tabela `fiscal_collection_plan`
+ *
+ * O plano responde a: para este cliente e esta competência, qual conector, qual
+ * documento, qual jurisdição, qual credencial, e o que falta. Cada uma dessas
+ * respostas já tem dono no banco — cobertura, prontidão da credencial,
+ * elegibilidade, autorização. Uma tabela de plano seria uma SEXTA cópia, que
+ * envelhece na primeira vez que uma das cinco mudar sem que alguém lembre de
+ * recalcular a sexta.
+ *
+ * Esta casa já pagou por isso: a 0055 criou `client_fiscal_credential` para um
+ * fato que `digital_certificate` já guardava, e a 0056 teve de removê-la. Um
+ * schema sem consumidor é invenção; um schema com o MESMO fato em dois lugares é
+ * pior, porque os dois respondem e discordam.
+ *
+ * Aqui o plano é uma projeção. Ele nasce da leitura, morre na resposta HTTP, e
+ * nunca diverge — porque não há de quê divergir.
+ *
+ * ## O que o plano NÃO faz
+ *
+ * Não executa, não autoriza e não liga nada. `readyForControlledTest` é um
+ * diagnóstico: significa que os insumos estão no lugar, não que alguém aprovou.
+ * A aprovação é `fiscal_run_authorization`, é humana, e é de uma execução só.
+ */
+export type CollectionBlocker = 'jurisdiction_unknown' | 'coverage_unknown' | 'coverage_unsupported' | 'credential_not_ready' | 'not_eligible' | 'connector_not_verified' | 'connector_not_implemented' | 'protocol_not_verified' | 'client_not_enrolled' | 'tenant_automation_disabled';
+export interface CollectionPlanEntry {
+    documentType: FiscalDocumentType;
+    /** Slug da fonte — o mesmo vocabulário de `fiscal_sync_cursor.source`. */
+    connector: string;
+    jurisdictionScope: string;
+    jurisdictionCode: string | null;
+    coverage: FiscalCoverage;
+    credentialState: string;
+    credentialKind: string | null;
+    /** Sempre `READ_ONLY` nesta fase, e a 0060 impede gravar outra coisa. */
+    operation: 'READ_ONLY';
+    /** Ninguém executa por conta própria nesta fase. */
+    executionMode: 'manual';
+    credentialLocalValid: boolean;
+    /** Uma autorização aqui seria de PRIMEIRO CONTATO, e a tela precisa dizer. */
+    firstContact: boolean;
+    connectorImplemented: boolean;
+    protocolVerified: boolean;
+    blockers: readonly CollectionBlocker[];
+    readyForControlledTest: boolean;
+    /** A autorização viva, se houver. `null` significa que falta o portão humano. */
+    authorization: FiscalRunAuthorization | null;
+}
+export interface CollectionPlan {
+    clientId: string;
+    competence: FiscalCompetence;
+    /** A sugestão que a tela exibe quando ninguém escolheu — nunca aplicada em silêncio. */
+    suggestedCompetence: FiscalCompetence;
+    environment: FiscalEnvironment;
+    entries: readonly CollectionPlanEntry[];
+    /** Verdadeiro só quando TODA entrada está pronta. Um bloqueio basta para negar. */
+    readyForControlledTest: boolean;
+}
+export declare function buildCollectionPlan(tx: Tx, input: {
+    clientId: string;
+    environment: FiscalEnvironment;
+    competenceYear?: number;
+    competenceMonth?: number;
+    documentTypes?: readonly FiscalDocumentType[];
+    now?: Date;
+}): Promise<CollectionPlan>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/fiscal/collection/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../../src/fiscal/collection/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAsC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAyB,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAExF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,MAAM,iBAAiB,GACzB,sBAAsB,GACtB,kBAAkB,GAClB,sBAAsB,GACtB,sBAAsB,GACtB,cAAc,GACd,wBAAwB,GAMxB,2BAA2B,GAC3B,uBAAuB,GACvB,qBAAqB,GACrB,4BAA4B,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,kBAAkB,CAAC;IACjC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,SAAS,EAAE,WAAW,CAAC;IACvB,oDAAoD;IACpD,aAAa,EAAE,QAAQ,CAAC;IACxB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8EAA8E;IAC9E,YAAY,EAAE,OAAO,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,sBAAsB,EAAE,OAAO,CAAC;IAChC,iFAAiF;IACjF,aAAa,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,wFAAwF;IACxF,mBAAmB,EAAE,gBAAgB,CAAC;IACtC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACxC,mFAAmF;IACnF,sBAAsB,EAAE,OAAO,CAAC;CACjC;AAkBD,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GACA,OAAO,CAAC,cAAc,CAAC,CAwGzB"}

package/dist/fiscal/collection/plan.js

@@ -0,0 +1,119 @@
+import { coverageForClient } from '../coverage/model.js';
+import { readFiscalCredentialReadiness } from '../credentials/readiness.js';
+import { evaluateFiscalEligibility } from '../eligibility.js';
+import { competenceOf, suggestCompetenceFor } from './competence.js';
+import { listRunAuthorizations } from './authorization.js';
+/**
+ * O conector de cada tipo de documento.
+ *
+ * Municipal e estadual são conectores SEPARADOS — foi o que o discovery desta
+ * fase confirmou, e é o que impede o erro de tratar "dar baixa nas notas" como
+ * uma coisa só. A NFS-e do município vem pelo ADN nacional (que é quem recebe o
+ * compartilhamento das prefeituras); a NF-e de entrada vem pela distribuição da
+ * SEFAZ. Mesmo certificado, protocolos distintos, cursores distintos.
+ */
+const CONNECTOR_BY_TYPE = {
+    nfse: 'nfse_adn',
+    nfe: 'sefaz_dfe',
+    cte: 'sefaz_dfe',
+    nfce: 'sefaz_dfe',
+};
+export async function buildCollectionPlan(tx, input) {
+    const now = input.now ?? new Date();
+    const suggested = suggestCompetenceFor(now);
+    const competence = input.competenceYear !== undefined && input.competenceMonth !== undefined
+        ? competenceOf(input.competenceYear, input.competenceMonth)
+        : suggested;
+    const types = input.documentTypes ?? ['nfse', 'nfe'];
+    const authorizations = await listRunAuthorizations(tx, input.clientId);
+    const entries = [];
+    for (const documentType of types) {
+        const connector = CONNECTOR_BY_TYPE[documentType];
+        const coverage = await coverageForClient(tx, { clientId: input.clientId, documentType });
+        const credential = await readFiscalCredentialReadiness(tx, {
+            clientId: input.clientId,
+            environment: input.environment,
+            source: connector,
+        });
+        const eligibility = await evaluateFiscalEligibility(tx, {
+            clientId: input.clientId,
+            documentType,
+            environment: input.environment,
+        });
+        const blockers = [];
+        if (!coverage.jurisdictionKnown)
+            blockers.push('jurisdiction_unknown');
+        if (coverage.coverageStatus === 'UNKNOWN')
+            blockers.push('coverage_unknown');
+        if (coverage.coverageStatus === 'UNSUPPORTED')
+            blockers.push('coverage_unsupported');
+        // A cobertura diz que o CAMINHO existe. Que ele já tenha respondido a este
+        // produto é outra afirmação, e ela mora em `verified_at` — vazio aqui
+        // significa que o conector nunca foi exercido, e o plano tem de dizer isso
+        // em vez de mostrar "conectado" por causa de um certificado salvo.
+        if (coverage.officialApiAvailable !== 'yes')
+            blockers.push('connector_not_verified');
+        // Cada camada com o seu nome. Fundir as três num "não está pronto" foi o que
+        // mandou o operador procurar no certificado um defeito de implementação.
+        if (!coverage.connectorImplemented)
+            blockers.push('connector_not_implemented');
+        else if (!coverage.protocolVerified)
+            blockers.push('protocol_not_verified');
+        // A credencial válida SÓ localmente não é mais um bloqueio absoluto: ela é
+        // exatamente o estado que o primeiro contato existe para atravessar. O que
+        // continua bloqueando é o cron — e este plano descreve a prova controlada,
+        // que é manual por definição.
+        if (!credential.usableByWorker && !credential.eligibleForFirstContact) {
+            blockers.push('credential_not_ready');
+        }
+        const motivos = new Set(eligibility.reasons);
+        if (motivos.has('client_not_enrolled'))
+            blockers.push('client_not_enrolled');
+        if (motivos.has('tenant_automation_disabled') || motivos.has('environment_mismatch')) {
+            blockers.push('tenant_automation_disabled');
+        }
+        // `credential_not_ready` da elegibilidade é esperado enquanto o aceite
+        // remoto não existir, e já está representado acima com a distinção certa.
+        const outros = [...motivos].filter((r) => r !== 'client_not_enrolled' &&
+            r !== 'tenant_automation_disabled' &&
+            r !== 'environment_mismatch' &&
+            r !== 'credential_not_ready' &&
+            r !== 'real_operation_not_declared');
+        if (outros.length > 0)
+            blockers.push('not_eligible');
+        const live = authorizations.find((a) => a.state === 'live' &&
+            a.source === connector &&
+            a.environment === input.environment &&
+            a.competence.year === competence.year &&
+            a.competence.month === competence.month);
+        entries.push({
+            documentType,
+            connector,
+            jurisdictionScope: coverage.jurisdictionScope,
+            jurisdictionCode: coverage.jurisdictionCode,
+            coverage,
+            credentialState: credential.state,
+            credentialKind: credential.kind,
+            /** O material abre aqui? Independente de algum ambiente já tê-lo aceito. */
+            credentialLocalValid: credential.localValid,
+            /** Esta prova, se autorizada, seria o primeiro contato com o ambiente. */
+            firstContact: credential.eligibleForFirstContact,
+            connectorImplemented: coverage.connectorImplemented,
+            protocolVerified: coverage.protocolVerified,
+            operation: 'READ_ONLY',
+            executionMode: 'manual',
+            blockers,
+            readyForControlledTest: blockers.length === 0,
+            authorization: live ?? null,
+        });
+    }
+    return {
+        clientId: input.clientId,
+        competence,
+        suggestedCompetence: suggested,
+        environment: input.environment,
+        entries,
+        readyForControlledTest: entries.length > 0 && entries.every((e) => e.readyForControlledTest),
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/fiscal/collection/plan.js.map

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