@baruk/core 0.4.2 → 0.6.0

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

@@ -0,0 +1,87 @@
+import type { Tx } from '../../db/client.js';
+import type { FiscalDocumentType } from '../ingestion/provider.js';
+/**
+ * Com que frequência — e a resposta padrão é "nenhuma".
+ *
+ * ## Duas rédeas, dois portões
+ *
+ * Elegibilidade (0055) responde QUEM pode entrar. Política responde QUANDO. São
+ * perguntas independentes, e mantê-las separadas paga em um caso concreto: no
+ * dia em que alguém inscrever a carteira inteira de uma vez — importação de
+ * clientes, um clique errado numa tela de lote — a frequência ainda será
+ * `disabled` para todos, e nenhuma consulta sai contra o ambiente nacional.
+ *
+ * Se as duas vivessem no mesmo campo, inscrever seria ligar.
+ *
+ * ## Herança com um nível, e nenhum default permissivo
+ *
+ * A linha do cliente vence a do escritório; a ausência das duas é `disabled`.
+ * Não existe "herda do produto" nem "se não disser, use diário": o padrão de
+ * fábrica de uma automação que consulta a Receita em nome de terceiros é
+ * desligada, e isso precisa valer também para quem esqueceu de configurar.
+ */
+export type FiscalSyncFrequency = 'disabled' | 'hourly' | 'daily' | 'business_day';
+export interface FiscalSyncPolicy {
+    frequency: FiscalSyncFrequency;
+    /** Hora local (America/Sao_Paulo) em que a janela diária abre. */
+    windowHourLocal: number;
+    /** De onde veio a decisão. `default` = nenhuma linha, logo desligado. */
+    origin: 'client' | 'tenant' | 'default';
+    enabled: boolean;
+}
+/** O que vale quando ninguém configurou nada. Desligado, sempre. */
+export declare const FISCAL_SYNC_POLICY_DEFAULT: FiscalSyncPolicy;
+/**
+ * Resolve a política de um cliente.
+ *
+ * Roda sob `withContext` com o tenant — a tabela tem RLS FORCE.
+ */
+export declare function resolveFiscalSyncPolicy(tx: Tx, input: {
+    clientId: string;
+    documentType: FiscalDocumentType;
+}): Promise<FiscalSyncPolicy>;
+/**
+ * Quando este fluxo volta a ser elegível, pela CADÊNCIA.
+ *
+ * Distinto de `next_attempt_after`, que é espera do PROVEDOR. Desobedecer aquela
+ * bloqueia o CNPJ do cliente; antecipar esta é só desperdício. O gate efetivo é
+ * o maior dos dois, e quem os combina é `nextEffectiveRun`.
+ *
+ * `business_day` avança para segunda quando cai no fim de semana. Não é
+ * cosmético: nota emitida no sábado só é vista na segunda de qualquer forma, e
+ * uma consulta que ninguém vai olhar ainda assim consome a cota do cliente.
+ */
+export declare function nextRunAfter(policy: FiscalSyncPolicy, lastCompletedAt: Date | null, now: Date): Date | null;
+/**
+ * O gate efetivo: o MAIOR entre a cadência nossa e a espera do provedor.
+ *
+ * Colapsá-los numa coluna só faria uma política diária apagar uma espera
+ * obrigatória de uma hora — e essa espera é o que separa a automação do
+ * `cStat 656`.
+ */
+export declare function nextEffectiveRun(cadence: Date | null, providerWait: Date | null): Date | null;
+/**
+ * Grava a política de cadência.
+ *
+ * ## Por que existe uma função, e não um `INSERT` em cada chamador
+ *
+ * Os índices únicos da 0058 são PARCIAIS (`WHERE client_id IS NOT NULL` e
+ * `WHERE client_id IS NULL`), porque NULL não colide com NULL num índice comum
+ * e sem isso o padrão do escritório poderia ser gravado duas vezes. A
+ * consequência é que `ON CONFLICT (tenant_id, client_id, document_type)`
+ * **não encontra o índice** — o PostgreSQL exige o predicado junto.
+ *
+ * É uma armadilha que todo chamador cairia uma vez. Uma função só, que a
+ * conhece, é mais barata do que três lugares que a redescobrem.
+ */
+export declare function setFiscalSyncPolicy(tx: Tx, input: {
+    tenantId: string;
+    /** `null` = padrão do escritório para aquele tipo. */
+    clientId: string | null;
+    documentType: FiscalDocumentType;
+    frequency: FiscalSyncFrequency;
+    windowHourLocal?: number;
+    enabledBy?: string | null;
+    now?: Date;
+}): Promise<void>;
+//# sourceMappingURL=policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/fiscal/sync/policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,cAAc,CAAC;AAEnF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACxC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,oEAAoE;AACpE,eAAO,MAAM,0BAA0B,EAAE,gBAKxC,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,kBAAkB,CAAA;CAAE,GAC5D,OAAO,CAAC,gBAAgB,CAAC,CAsB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,gBAAgB,EACxB,eAAe,EAAE,IAAI,GAAG,IAAI,EAC5B,GAAG,EAAE,IAAI,GACR,IAAI,GAAG,IAAI,CA0Bb;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,EAAE,YAAY,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAI7F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,EAAE,EACN,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,kBAAkB,CAAC;IACjC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GACA,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/fiscal/sync/policy.js

@@ -0,0 +1,136 @@
+import { uuidv7 } from '@baruk/shared';
+/** O que vale quando ninguém configurou nada. Desligado, sempre. */
+export const FISCAL_SYNC_POLICY_DEFAULT = {
+    frequency: 'disabled',
+    windowHourLocal: 8,
+    origin: 'default',
+    enabled: false,
+};
+/**
+ * Resolve a política de um cliente.
+ *
+ * Roda sob `withContext` com o tenant — a tabela tem RLS FORCE.
+ */
+export async function resolveFiscalSyncPolicy(tx, input) {
+    const rows = await tx `
+    SELECT client_id, frequency, window_hour_local
+      FROM fiscal_sync_policy
+     WHERE document_type = ${input.documentType}
+       AND (client_id = ${input.clientId} OR client_id IS NULL)
+     -- A linha do cliente primeiro: "NULLS LAST" faz o padrão do escritório
+     -- ficar para trás sem precisar de duas consultas.
+     ORDER BY client_id NULLS LAST
+     LIMIT 1
+  `;
+    const r = rows[0];
+    if (!r)
+        return FISCAL_SYNC_POLICY_DEFAULT;
+    const frequency = r.frequency;
+    return {
+        frequency,
+        windowHourLocal: r.window_hour_local,
+        origin: r.client_id ? 'client' : 'tenant',
+        enabled: frequency !== 'disabled',
+    };
+}
+/**
+ * Quando este fluxo volta a ser elegível, pela CADÊNCIA.
+ *
+ * Distinto de `next_attempt_after`, que é espera do PROVEDOR. Desobedecer aquela
+ * bloqueia o CNPJ do cliente; antecipar esta é só desperdício. O gate efetivo é
+ * o maior dos dois, e quem os combina é `nextEffectiveRun`.
+ *
+ * `business_day` avança para segunda quando cai no fim de semana. Não é
+ * cosmético: nota emitida no sábado só é vista na segunda de qualquer forma, e
+ * uma consulta que ninguém vai olhar ainda assim consome a cota do cliente.
+ */
+export function nextRunAfter(policy, lastCompletedAt, now) {
+    if (!policy.enabled)
+        return null;
+    const base = lastCompletedAt ?? now;
+    if (policy.frequency === 'hourly') {
+        return new Date(base.getTime() + 3_600_000);
+    }
+    // A janela diária é ancorada na hora LOCAL do escritório. O deslocamento é
+    // fixo em -3 porque o Brasil não tem mais horário de verão desde 2019; se
+    // voltar, este é o ponto único a mudar — e o comentário é o que faz alguém
+    // encontrá-lo.
+    const OFFSET_HOURS = -3;
+    const alvo = new Date(base.getTime());
+    alvo.setUTCHours(policy.windowHourLocal - OFFSET_HOURS, 0, 0, 0);
+    if (alvo <= base)
+        alvo.setUTCDate(alvo.getUTCDate() + 1);
+    if (policy.frequency === 'business_day') {
+        // 0 = domingo, 6 = sábado, no fuso local.
+        for (let i = 0; i < 7; i += 1) {
+            const localDay = new Date(alvo.getTime() + OFFSET_HOURS * 3_600_000).getUTCDay();
+            if (localDay !== 0 && localDay !== 6)
+                break;
+            alvo.setUTCDate(alvo.getUTCDate() + 1);
+        }
+    }
+    return alvo;
+}
+/**
+ * O gate efetivo: o MAIOR entre a cadência nossa e a espera do provedor.
+ *
+ * Colapsá-los numa coluna só faria uma política diária apagar uma espera
+ * obrigatória de uma hora — e essa espera é o que separa a automação do
+ * `cStat 656`.
+ */
+export function nextEffectiveRun(cadence, providerWait) {
+    if (!cadence)
+        return providerWait;
+    if (!providerWait)
+        return cadence;
+    return cadence > providerWait ? cadence : providerWait;
+}
+/**
+ * Grava a política de cadência.
+ *
+ * ## Por que existe uma função, e não um `INSERT` em cada chamador
+ *
+ * Os índices únicos da 0058 são PARCIAIS (`WHERE client_id IS NOT NULL` e
+ * `WHERE client_id IS NULL`), porque NULL não colide com NULL num índice comum
+ * e sem isso o padrão do escritório poderia ser gravado duas vezes. A
+ * consequência é que `ON CONFLICT (tenant_id, client_id, document_type)`
+ * **não encontra o índice** — o PostgreSQL exige o predicado junto.
+ *
+ * É uma armadilha que todo chamador cairia uma vez. Uma função só, que a
+ * conhece, é mais barata do que três lugares que a redescobrem.
+ */
+export async function setFiscalSyncPolicy(tx, input) {
+    const now = input.now ?? new Date();
+    // Ligado exige registro de quem ligou e quando — o CHECK da 0058 recusa
+    // automação sem dono, e a data é gravada aqui em vez de num `DEFAULT`.
+    const enabledAt = input.frequency === 'disabled' ? null : now;
+    const hora = input.windowHourLocal ?? 8;
+    if (input.clientId) {
+        await tx `
+      INSERT INTO fiscal_sync_policy (id, tenant_id, client_id, document_type, frequency,
+                                      window_hour_local, enabled_at, enabled_by, updated_at)
+      VALUES (${uuidv7()}, ${input.tenantId}, ${input.clientId}, ${input.documentType},
+              ${input.frequency}, ${hora}, ${enabledAt}, ${input.enabledBy ?? null}, now())
+      ON CONFLICT (tenant_id, client_id, document_type) WHERE client_id IS NOT NULL
+      DO UPDATE SET frequency = EXCLUDED.frequency,
+                    window_hour_local = EXCLUDED.window_hour_local,
+                    enabled_at = EXCLUDED.enabled_at,
+                    enabled_by = EXCLUDED.enabled_by,
+                    updated_at = now()
+    `;
+        return;
+    }
+    await tx `
+    INSERT INTO fiscal_sync_policy (id, tenant_id, client_id, document_type, frequency,
+                                    window_hour_local, enabled_at, enabled_by, updated_at)
+    VALUES (${uuidv7()}, ${input.tenantId}, NULL, ${input.documentType},
+            ${input.frequency}, ${hora}, ${enabledAt}, ${input.enabledBy ?? null}, now())
+    ON CONFLICT (tenant_id, document_type) WHERE client_id IS NULL
+    DO UPDATE SET frequency = EXCLUDED.frequency,
+                  window_hour_local = EXCLUDED.window_hour_local,
+                  enabled_at = EXCLUDED.enabled_at,
+                  enabled_by = EXCLUDED.enabled_by,
+                  updated_at = now()
+  `;
+}
+//# sourceMappingURL=policy.js.map

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

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

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

@@ -0,0 +1,76 @@
+import type { Tx } from '../../db/client.js';
+import { type IngestionDeps } from '../ingestion/pipeline.js';
+/**
+ * A segunda chance dos itens que ficaram guardados.
+ *
+ * ## Por que os bytes foram preservados, afinal
+ *
+ * A Fase 1 guarda o XML original de todo item que não pôde ser interpretado.
+ * Isso só tem valor se houver um caminho de volta: **o parser melhora**. Um
+ * leiaute que este código não sabia ler em setembro é legível depois de um
+ * deploy, e o item guardado é a única forma de aproveitá-lo sem pedir nada ao
+ * provedor — que é a única forma que não gasta a cota do cliente.
+ *
+ * Sem reprocessamento, a caixa de entrada é um cemitério com boa intenção.
+ *
+ * ## As três garantias, e como cada uma é obtida
+ *
+ *   **não duplica documento**  o `INSERT` usa `ON CONFLICT DO NOTHING` sobre o
+ *                              índice de deduplicação. Não há `SELECT` antes,
+ *                              logo não há janela entre verificar e inserir.
+ *   **não duplica evento**     mesmo mecanismo, sobre o índice do evento.
+ *   **não move o cursor**      `reingestPreservedItem` simplesmente não o toca.
+ *                              O item já está guardado e a posição do provedor
+ *                              passou por ele há muito tempo; mexer aqui só
+ *                              poderia fazer mal, nos dois sentidos.
+ *
+ * ## A promoção do evento é feita AQUI, e não pelo pipeline
+ *
+ * Um item inválido que se revela evento poderia ser reenviado ao pipeline, que
+ * o enfileiraria como pendente — criando uma SEGUNDA linha para os MESMOS
+ * bytes, com a antiga presa em `invalid` para sempre. A linha é promovida no
+ * lugar: mesma identidade, mesmo `raw`, estado novo.
+ */
+export type ReprocessOutcome = 'document_created' | 'document_duplicate' | 'event_applied' | 'event_pending' | 'still_invalid' | 'already_resolved' | 'not_found';
+export interface ReprocessResult {
+    inboxId: string;
+    outcome: ReprocessOutcome;
+    detail: string;
+    documentId: string | null;
+    reconciled: number;
+}
+/**
+ * Reprocessa um item preservado.
+ *
+ * `deps.adapter` precisa ser o adapter da MESMA fonte que guardou o item —
+ * outro leiaute produziria uma interpretação errada de bytes válidos. Quem
+ * chama confere; a rota faz isso pela `source` gravada na linha.
+ */
+export declare function reprocessFiscalInboxItem(tx: Tx, deps: IngestionDeps, input: {
+    tenantId: string;
+    inboxId: string;
+    actorDocument: string;
+    actorId?: string | null;
+    now?: Date;
+}): Promise<ReprocessResult>;
+export interface InboxItemRow {
+    id: string;
+    clientId: string;
+    clientName: string | null;
+    source: string;
+    environment: string;
+    sourceNsu: string | null;
+    state: string;
+    eventType: string | null;
+    targetAccessKey: string | null;
+    rejectReason: string | null;
+    receivedAt: string;
+    reprocessCount: number;
+    sizeBytes: number;
+}
+/** A caixa de entrada, para a tela. Sem o `raw` — bytes não vão em JSON de API. */
+export declare function listFiscalInbox(tx: Tx, input?: {
+    state?: 'pending_target' | 'invalid' | 'applied' | 'any';
+    limit?: number;
+}): Promise<InboxItemRow[]>;
+//# sourceMappingURL=reprocess.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reprocess.d.ts","sourceRoot":"","sources":["../../../src/fiscal/sync/reprocess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAIlC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,gBAAgB,GACxB,kBAAkB,GAClB,oBAAoB,GACpB,eAAe,GACf,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,WAAW,CAAC;AAEhB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,EAAE,EACN,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE;IACL,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GACA,OAAO,CAAC,eAAe,CAAC,CAwM1B;AA4BD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,KAAK,GAAE;IAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACvF,OAAO,CAAC,YAAY,EAAE,CAAC,CA4CzB"}

package/dist/fiscal/sync/reprocess.js

@@ -0,0 +1,237 @@
+import { appendAudit } from '../../audit/audit.js';
+import { reingestPreservedItem, reconcileFiscalPendingEvents, } from '../ingestion/pipeline.js';
+/**
+ * Reprocessa um item preservado.
+ *
+ * `deps.adapter` precisa ser o adapter da MESMA fonte que guardou o item —
+ * outro leiaute produziria uma interpretação errada de bytes válidos. Quem
+ * chama confere; a rota faz isso pela `source` gravada na linha.
+ */
+export async function reprocessFiscalInboxItem(tx, deps, input) {
+    const now = input.now ?? new Date();
+    const [row] = await tx `
+    SELECT id, client_id, source, source_environment, source_nsu, state,
+           document_type, raw, reject_reason
+      FROM fiscal_ingestion_inbox
+     WHERE id = ${input.inboxId}
+  `;
+    if (!row) {
+        return {
+            inboxId: input.inboxId,
+            outcome: 'not_found',
+            detail: 'item não encontrado',
+            documentId: null,
+            reconciled: 0,
+        };
+    }
+    const base = {
+        tenantId: input.tenantId,
+        clientId: row.client_id,
+        actorDocument: input.actorDocument,
+        environment: row.source_environment,
+        documentType: (row.document_type ?? 'nfse'),
+        now,
+        actorId: input.actorId ?? null,
+    };
+    // Já aplicado: reprocessar não é erro, e não faz nada. Devolver isso é melhor
+    // do que reingerir bytes que já viraram linha — seria trabalho para produzir
+    // uma duplicata que o banco recusaria de qualquer forma.
+    if (row.state === 'applied') {
+        return {
+            inboxId: row.id,
+            outcome: 'already_resolved',
+            detail: 'item já aplicado',
+            documentId: null,
+            reconciled: 0,
+        };
+    }
+    // Pendente: o que falta não é interpretar, é o alvo existir. Reconciliar é a
+    // operação certa, e ela é idempotente por construção.
+    if (row.state === 'pending_target') {
+        const reconciled = await reconcileFiscalPendingEvents(tx, deps, {
+            tenantId: input.tenantId,
+            clientId: row.client_id,
+        });
+        await auditar(tx, input, row, reconciled > 0 ? 'event_applied' : 'event_pending', reconciled);
+        return {
+            inboxId: row.id,
+            outcome: reconciled > 0 ? 'event_applied' : 'event_pending',
+            detail: reconciled > 0
+                ? 'documento-alvo encontrado; evento aplicado'
+                : 'documento-alvo ainda não chegou',
+            documentId: null,
+            reconciled,
+        };
+    }
+    // Inválido: tenta interpretar de novo com o parser ATUAL.
+    const doc = {
+        nsu: row.source_nsu ?? '0',
+        raw: new Uint8Array(row.raw),
+        mimeType: 'application/xml',
+    };
+    let parsed;
+    try {
+        parsed = deps.adapter.parse(doc);
+    }
+    catch (err) {
+        const reason = err ? 'parse_failed' : 'parse_failed';
+        await tx `
+      UPDATE fiscal_ingestion_inbox
+         SET reprocessed_at = ${now}, reprocess_count = reprocess_count + 1,
+             reject_reason = ${reason}
+       WHERE id = ${row.id}
+    `;
+        return {
+            inboxId: row.id,
+            outcome: 'still_invalid',
+            detail: 'o parser atual ainda não lê este item',
+            documentId: null,
+            reconciled: 0,
+        };
+    }
+    if (parsed.event) {
+        // Promoção NO LUGAR. `dedupe_key` muda de `raw:<sha>` para a identidade
+        // real do evento, e é aí que pode haver conflito com um evento idêntico já
+        // guardado — caso em que este item é redundante e o outro já o preserva.
+        try {
+            await tx.savepoint((sp) => sp `
+        UPDATE fiscal_ingestion_inbox
+           SET state             = 'pending_target',
+               document_type     = ${parsed.documentType},
+               event_type        = ${parsed.event.type},
+               event_code        = ${parsed.event.code ?? null},
+               event_sequence    = ${parsed.event.sequence ?? null},
+               occurred_at       = ${parsed.event.occurredAt ?? null},
+               target_access_key = ${parsed.event.targetAccessKey},
+               dedupe_key        = ${parsed.dedupeKey},
+               reject_reason     = NULL,
+               reprocessed_at    = ${now},
+               reprocess_count   = reprocess_count + 1
+         WHERE id = ${row.id}
+      `);
+        }
+        catch {
+            await tx `
+        UPDATE fiscal_ingestion_inbox
+           SET reprocessed_at = ${now}, reprocess_count = reprocess_count + 1,
+               reject_reason = 'duplicate_of_existing_event'
+         WHERE id = ${row.id}
+      `;
+            return {
+                inboxId: row.id,
+                outcome: 'still_invalid',
+                detail: 'evento idêntico já preservado em outro item',
+                documentId: null,
+                reconciled: 0,
+            };
+        }
+        const reconciled = await reconcileFiscalPendingEvents(tx, deps, {
+            tenantId: input.tenantId,
+            clientId: row.client_id,
+        });
+        await auditar(tx, input, row, reconciled > 0 ? 'event_applied' : 'event_pending', reconciled);
+        return {
+            inboxId: row.id,
+            outcome: reconciled > 0 ? 'event_applied' : 'event_pending',
+            detail: reconciled > 0
+                ? 'reinterpretado como evento e aplicado'
+                : 'reinterpretado como evento; alvo ainda não existe',
+            documentId: null,
+            reconciled,
+        };
+    }
+    // Documento. O pipeline grava com a MESMA dedupe do caminho normal.
+    const resultado = await reingestPreservedItem(tx, deps, base, doc);
+    if (resultado.kind === 'still_invalid') {
+        await tx `
+      UPDATE fiscal_ingestion_inbox
+         SET reprocessed_at = ${now}, reprocess_count = reprocess_count + 1,
+             reject_reason = ${resultado.reason}
+       WHERE id = ${row.id}
+    `;
+        return {
+            inboxId: row.id,
+            outcome: 'still_invalid',
+            detail: resultado.reason,
+            documentId: null,
+            reconciled: 0,
+        };
+    }
+    // Duplicata quer dizer que o documento JÁ existe — o item está resolvido do
+    // mesmo jeito, e apontar para a linha existente é mais útil do que apontar
+    // para nada.
+    const documentId = resultado.kind === 'document_created'
+        ? resultado.documentId
+        : ((await tx `
+            SELECT id FROM fiscal_document
+             WHERE client_id = ${row.client_id} AND dedupe_key = ${parsed.dedupeKey}
+             LIMIT 1
+          `)[0]?.id ?? null);
+    await tx `
+    UPDATE fiscal_ingestion_inbox
+       SET state = 'applied', applied_at = ${now}, applied_document_id = ${documentId},
+           reject_reason = NULL, reprocessed_at = ${now},
+           reprocess_count = reprocess_count + 1
+     WHERE id = ${row.id}
+  `;
+    await auditar(tx, input, row, resultado.kind === 'document_created' ? 'document_created' : 'document_duplicate', 0);
+    return {
+        inboxId: row.id,
+        outcome: resultado.kind === 'document_created' ? 'document_created' : 'document_duplicate',
+        detail: resultado.kind === 'document_created'
+            ? 'reinterpretado como documento e gravado'
+            : 'documento já existia; item marcado como resolvido',
+        documentId,
+        reconciled: 0,
+    };
+}
+/** Trilha: contadores e identificadores. Nunca XML, nunca nome, nunca valor. */
+async function auditar(tx, input, row, outcome, reconciled) {
+    await appendAudit(tx, {
+        actorType: input.actorId ? 'user' : 'system',
+        actorId: input.actorId ?? null,
+        action: 'fiscal.inbox.reprocessed',
+        resourceType: 'fiscal_ingestion_inbox',
+        resourceId: row.id,
+        metadata: {
+            clientId: row.client_id,
+            source: row.source,
+            environment: row.source_environment,
+            previousState: row.state,
+            previousReason: row.reject_reason,
+            outcome,
+            reconciled,
+        },
+    });
+}
+/** A caixa de entrada, para a tela. Sem o `raw` — bytes não vão em JSON de API. */
+export async function listFiscalInbox(tx, input = {}) {
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500);
+    const state = input.state ?? 'any';
+    const rows = await tx `
+    SELECT i.id, i.client_id, c.display_name AS client_name, i.source, i.source_environment,
+           i.source_nsu, i.state, i.event_type, i.target_access_key, i.reject_reason,
+           i.received_at, i.reprocess_count, octet_length(i.raw) AS size_bytes
+      FROM fiscal_ingestion_inbox i
+      LEFT JOIN client c ON c.id = i.client_id
+     WHERE ${state === 'any' ? tx `true` : tx `i.state = ${state}`}
+     ORDER BY i.received_at DESC
+     LIMIT ${limit}
+  `;
+    return rows.map((r) => ({
+        id: r.id,
+        clientId: r.client_id,
+        clientName: r.client_name,
+        source: r.source,
+        environment: r.source_environment,
+        sourceNsu: r.source_nsu,
+        state: r.state,
+        eventType: r.event_type,
+        targetAccessKey: r.target_access_key,
+        rejectReason: r.reject_reason,
+        receivedAt: r.received_at.toISOString(),
+        reprocessCount: r.reprocess_count,
+        sizeBytes: r.size_bytes,
+    }));
+}
+//# sourceMappingURL=reprocess.js.map

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

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

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

@@ -0,0 +1,82 @@
+import type { FiscalProviderErrorClass } from '../ingestion/provider.js';
+import { type FiscalTransportErrorClass } from '../transport/types.js';
+/**
+ * O que fazer depois de uma falha — e, sobretudo, o que NÃO fazer.
+ *
+ * ## Nem toda falha merece retentativa, e a maioria dos danos vem daí
+ *
+ * A forma óbvia de um worker é `catch { retry() }`. Aplicada ao ambiente
+ * nacional, ela produz o cenário exato que a norma pune: uma consulta recusada
+ * por espera obrigatória é reenviada em segundos, o servidor devolve
+ * `cStat 656 — Consumo Indevido`, e o CNPJ bloqueado é o do CLIENTE. Retentar
+ * uma recusa por consumo indevido é acelerar o dano, não corrigi-lo.
+ *
+ * Certificado vencido é o oposto e igualmente errado de retentar: nenhuma
+ * quantidade de tentativas renova um A1. Insistir só transforma um problema
+ * resolvível numa fila de erros que ninguém lê.
+ *
+ * ## Por que uma taxonomia própria, e não a classe do provedor
+ *
+ * `FiscalProviderErrorClass` descreve o que o PROVEDOR disse. `FiscalTransportErrorClass`
+ * descreve o que a REDE fez. Nenhuma das duas diz o que o worker deve fazer — e
+ * as duas precisam colapsar numa decisão só, porque `timeout` de socket e
+ * `cStat 108 serviço paralisado` pedem exatamente o mesmo tratamento.
+ *
+ * Esta taxonomia é a terceira, e é a única sobre a qual há decisão.
+ */
+export type FiscalFailureCategory = 'NETWORK_TRANSIENT' | 'PROVIDER_RATE_LIMIT' | 'PROVIDER_TEMPORARILY_UNAVAILABLE' | 'AUTHENTICATION_FAILED' | 'CERTIFICATE_INVALID' | 'CERTIFICATE_EXPIRED' | 'PERMISSION_DENIED' | 'BAD_RESPONSE' | 'MALFORMED_DOCUMENT' | 'CURSOR_CONFLICT' | 'INTERNAL_ERROR';
+export interface FiscalRetryDecision {
+    category: FiscalFailureCategory;
+    /** `false` = nenhuma tentativa futura muda o desfecho sem ação humana. */
+    retryable: boolean;
+    /** Quando tentar de novo. `null` quando não se tenta. */
+    nextAttemptAt: Date | null;
+    /** Conta para o circuito do PROVEDOR? Falha de um cliente só, não. */
+    countsAgainstProvider: boolean;
+    /** Motivo de fila humana, quando o caso exige pessoa. */
+    interventionKind: 'auth_required' | 'certificate_expired' | 'certificate_invalid' | 'provider_access_denied' | 'repeated_failure' | null;
+    /** Código curto para trilha. Nunca a mensagem do provedor. */
+    code: string;
+}
+/** Classe do provedor → categoria de decisão. */
+export declare function categorizeProviderError(cls: FiscalProviderErrorClass): FiscalFailureCategory;
+/** Classe do transporte → categoria de decisão. */
+export declare function categorizeTransportError(cls: FiscalTransportErrorClass): FiscalFailureCategory;
+/** Status HTTP → categoria, para provedores REST (o ADN é um). */
+export declare function categorizeHttpStatus(status: number): FiscalFailureCategory;
+export interface RetryInput {
+    /** Quantas tentativas consecutivas já falharam ANTES desta. 0 na primeira. */
+    previousFailures: number;
+    now: Date;
+    /** Espera pedida pelo servidor. Quando vem, ela manda. */
+    retryAfter?: Date | null;
+    /**
+     * Fonte de aleatoriedade do jitter, em [0,1). Injetável para que o teste
+     * meça o intervalo e não a sorte.
+     */
+    random?: () => number;
+    /** Teto de falhas consecutivas antes de o caso virar tarefa humana. */
+    humanEscalationAfter?: number;
+}
+/**
+ * Decide o que fazer com uma falha.
+ *
+ * ## Jitter é obrigatório, não enfeite
+ *
+ * Sem ele, cem clientes que falharam no mesmo minuto voltam no mesmo minuto —
+ * o rebanho que derruba o provedor de novo assim que ele levanta. O jitter é
+ * "full jitter": um sorteio em `[0, espera]`, e não `espera ± 10%`. A variante
+ * completa é a que realmente espalha; a estreita só desloca o rebanho.
+ *
+ * ## `Retry-After` vence o nosso cálculo — com piso
+ *
+ * Quando o servidor diz quando voltar, ele sabe mais do que nós. Mas um
+ * `Retry-After: 0` num 429 é o servidor se contradizendo; o piso de 60s existe
+ * para que a obediência não vire laço.
+ */
+export declare function decideFiscalRetry(category: FiscalFailureCategory, input: RetryInput, 
+/** Código curto do provedor/transporte. Sem ele, a categoria serve de rótulo. */
+code?: string): FiscalRetryDecision;
+/** Atalho: recebe o erro e devolve a decisão, sem quem chama classificar antes. */
+export declare function decideFromError(err: unknown, input: RetryInput): FiscalRetryDecision;
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/fiscal/sync/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAwB,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAG7F;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,qBAAqB,GAC7B,mBAAmB,GACnB,qBAAqB,GACrB,kCAAkC,GAClC,uBAAuB,GACvB,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,yDAAyD;IACzD,aAAa,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,sEAAsE;IACtE,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yDAAyD;IACzD,gBAAgB,EACZ,eAAe,GACf,qBAAqB,GACrB,qBAAqB,GACrB,wBAAwB,GACxB,kBAAkB,GAClB,IAAI,CAAC;IACT,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;CACd;AAqDD,iDAAiD;AACjD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,wBAAwB,GAAG,qBAAqB,CAiB5F;AAED,mDAAmD;AACnD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,yBAAyB,GAAG,qBAAqB,CAe9F;AAED,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,qBAAqB,CAS1E;AAED,MAAM,WAAW,UAAU;IACzB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,EAAE,IAAI,CAAC;IACV,0DAA0D;IAC1D,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,qBAAqB,EAC/B,KAAK,EAAE,UAAU;AACjB,iFAAiF;AACjF,IAAI,GAAE,MAAiB,GACtB,mBAAmB,CA+CrB;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,mBAAmB,CAkBpF"}