@baruk/core 0.4.2 → 0.5.0

package/dist/fiscal/ingestion/pipeline.js

@@ -0,0 +1,699 @@
+import { uuidv7 } from '@baruk/shared';
+import { sha256Hex } from '../../storage/checksum.js';
+import { buildStorageKey } from '../../storage/key.js';
+import { appendAudit } from '../../audit/audit.js';
+import { evaluateFiscalEligibility } from '../eligibility.js';
+import { classifyFiscalDirection } from './direction.js';
+import { FiscalProviderError, } from './provider.js';
+/**
+ * `synthetic` no motor de elegibilidade e no ambiente do adapter são o mesmo
+ * eixo, então a conversão é identidade — declarada explicitamente para que uma
+ * divergência futura entre os dois vocabulários quebre a compilação em vez de
+ * abrir um fallback silencioso.
+ */
+const ENVIRONMENT_MAP = {
+    synthetic: 'synthetic',
+    homologation: 'homologation',
+    production: 'production',
+};
+export async function ingestFiscalDocuments(tx, deps, request) {
+    const now = request.now ?? new Date();
+    const env = ENVIRONMENT_MAP[request.environment];
+    const { adapter } = deps;
+    const blocked = (outcome, detail, errorClass = null, cursorBefore = null) => ({
+        outcome,
+        documentsFetched: 0,
+        documentsNew: 0,
+        documentsDuplicate: 0,
+        documentsFailed: 0,
+        eventsPending: 0,
+        eventsReconciled: 0,
+        eventsApplied: 0,
+        cursorBefore,
+        cursorAfter: cursorBefore,
+        allItemsPreserved: true,
+        errorClass,
+        detail,
+        documentIds: [],
+    });
+    // ── 1 · O adapter sabe operar neste ambiente? ────────────────────────────
+    if (!adapter.environments.includes(env)) {
+        // Não é erro de configuração do escritório: é um adapter sendo usado onde
+        // não se declarou capaz. Fechar aqui impede que um adapter sintético seja
+        // apontado para produção por engano de fiação.
+        return blocked('blocked_contract', `adapter "${adapter.source}" não opera o ambiente "${env}"`);
+    }
+    // ── 2 · Elegibilidade e credencial, nesta ordem ──────────────────────────
+    const eligibility = await evaluateFiscalEligibility(tx, {
+        clientId: request.clientId,
+        documentType: request.documentType,
+        environment: request.environment,
+    });
+    if (!eligibility.eligible) {
+        // Credencial é motivo SEPARADO de elegibilidade, mesmo sendo uma das
+        // camadas dela: "falta o certificado" e "este escritório não ligou a
+        // automação" pedem ações de pessoas diferentes.
+        const onlyCredential = eligibility.reasons.length === 1 && eligibility.reasons[0] === 'credential_not_ready';
+        return blocked(onlyCredential ? 'blocked_credential' : 'blocked_eligibility', eligibility.detail);
+    }
+    // ── 3 · Cursor e espera obrigatória ──────────────────────────────────────
+    const cursor = await loadCursor(tx, request, adapter.source, env);
+    const cursorBefore = cursor?.last_nsu ?? null;
+    if (cursor?.next_attempt_after && cursor.next_attempt_after > now) {
+        // A espera é do provedor, não nossa. Insistir aqui é o caminho direto para
+        // o 656 — e o bloqueio recai sobre o CNPJ do cliente.
+        return blocked('throttled', `espera obrigatória do provedor até ${cursor.next_attempt_after.toISOString()}`, 'throttled', cursorBefore);
+    }
+    // ── 4 · Busca ────────────────────────────────────────────────────────────
+    let fetched;
+    try {
+        fetched = await adapter.fetchBatch({
+            actorDocument: request.actorDocument,
+            fromNsu: cursorBefore,
+            environment: env,
+            batchLimit: adapter.batchLimit,
+        });
+    }
+    catch (err) {
+        const provider = err instanceof FiscalProviderError
+            ? err
+            : new FiscalProviderError('unknown', 'falha não classificada do provedor');
+        await recordFailure(tx, request, adapter.source, env, provider, now, cursorBefore, adapter.contractVersion ?? null);
+        return {
+            ...blocked('provider_error', describeProviderError(provider), provider.errorClass, cursorBefore),
+            outcome: 'provider_error',
+        };
+    }
+    // ── 5 · Persistência, item a item ────────────────────────────────────────
+    //
+    // Um documento ilegível no meio do lote NÃO derruba o lote — mas também não
+    // é descartado: ele vai para a caixa de entrada com os bytes originais, e é
+    // ISSO que autoriza o cursor a passar por cima dele. Travar a carteira
+    // inteira num único XML malformado seria pior; perdê-lo seria pior ainda.
+    let novos = 0;
+    let duplicados = 0;
+    let falhos = 0;
+    let pendentes = 0;
+    let aplicados = 0;
+    const ids = [];
+    let ultimoOk = cursorBefore;
+    let todosPreservados = true;
+    let primeiraFalhaDeGuarda = null;
+    for (const doc of fetched.documents) {
+        const disposition = await handleItem(tx, deps, request, adapter, env, doc, now);
+        switch (disposition.kind) {
+            case 'document_created':
+                novos += 1;
+                ids.push(disposition.id);
+                break;
+            case 'document_duplicate':
+                duplicados += 1;
+                break;
+            case 'event_applied':
+                aplicados += 1;
+                ids.push(disposition.id);
+                break;
+            case 'event_pending':
+                pendentes += 1;
+                break;
+            case 'event_duplicate':
+                duplicados += 1;
+                break;
+            case 'invalid_preserved':
+                falhos += 1;
+                break;
+            case 'unpreserved':
+                falhos += 1;
+                break;
+        }
+        if (disposition.kind === 'unpreserved') {
+            // O cursor é marca d'água: nada depois deste item pode ser commitado,
+            // mesmo que grave com sucesso. Parar aqui é o que impede o buraco.
+            todosPreservados = false;
+            primeiraFalhaDeGuarda = disposition.reason;
+            break;
+        }
+        ultimoOk = doc.nsu;
+    }
+    // ── 6 · Reconciliação: quem estava esperando já tem alvo? ────────────────
+    //
+    // Depois do lote, e não durante: um evento pode chegar no NSU 100 e o
+    // documento no 101, dentro do MESMO lote. Varrer no fim cobre esse caso e
+    // também o evento guardado por uma execução anterior — inclusive uma que
+    // morreu antes de reconciliar.
+    const reconciliados = await reconcileFiscalPendingEvents(tx, deps, request);
+    // ── 7 · COMMIT do cursor, por último ─────────────────────────────────────
+    //
+    // A posição do servidor só é adotada quando TUDO ficou preservado. Adotá-la
+    // com um buraco no meio do lote é exatamente como o NSU de um evento sumia.
+    const cursorAfter = todosPreservados ? (fetched.lastNsu ?? ultimoOk) : ultimoOk;
+    const exhausted = todosPreservados &&
+        (fetched.exhausted || (cursorAfter !== null && cursorAfter === fetched.maxNsu));
+    const nextAttempt = exhausted
+        ? new Date(now.getTime() + adapter.exhaustedBackoffSeconds * 1000)
+        : todosPreservados
+            ? null
+            : // Item não preservável é determinístico: repetir de imediato seria o
+                // laço que o cStat 656 pune. Recua como falha transitória.
+                new Date(now.getTime() + 300_000);
+    await saveCursor(tx, request, adapter.source, env, {
+        lastNsu: cursorAfter,
+        maxNsu: fetched.maxNsu,
+        lastSuccessAt: now,
+        nextAttemptAfter: nextAttempt,
+        preserved: todosPreservados,
+    });
+    const outcome = !todosPreservados
+        ? 'failed'
+        : fetched.documents.length === 0
+            ? 'no_documents'
+            : 'completed';
+    const report = {
+        outcome,
+        documentsFetched: fetched.documents.length,
+        documentsNew: novos,
+        documentsDuplicate: duplicados,
+        documentsFailed: falhos,
+        eventsPending: pendentes,
+        eventsReconciled: reconciliados,
+        eventsApplied: aplicados,
+        cursorBefore,
+        cursorAfter,
+        allItemsPreserved: todosPreservados,
+        errorClass: todosPreservados ? null : 'transient',
+        detail: !todosPreservados
+            ? `cursor retido: item não pôde ser preservado (${primeiraFalhaDeGuarda ?? 'motivo não classificado'})`
+            : exhausted
+                ? 'lote concluído; provedor sem mais documentos'
+                : 'lote concluído',
+        documentIds: ids,
+    };
+    await recordRun(tx, request, adapter.source, env, report, now, adapter.contractVersion ?? null);
+    await appendAudit(tx, {
+        actorType: 'system',
+        actorId: request.actorId ?? null,
+        action: 'fiscal.documents.synced',
+        resourceType: 'client',
+        resourceId: request.clientId,
+        // Contadores e cursor. Nunca XML, nunca nome de emitente, nunca valor.
+        metadata: {
+            source: adapter.source,
+            environment: env,
+            documentType: request.documentType,
+            fetched: report.documentsFetched,
+            created: report.documentsNew,
+            duplicate: report.documentsDuplicate,
+            failed: report.documentsFailed,
+            pending: report.eventsPending,
+            reconciled: report.eventsReconciled,
+            cursorBefore,
+            cursorAfter,
+            allItemsPreserved: report.allItemsPreserved,
+        },
+    });
+    return report;
+}
+/**
+ * Um item do lote, do XML bruto ao desfecho.
+ *
+ * Toda saída deste caminho é um desfecho NOMEADO. Não há `return` silencioso, e
+ * é por isso que o cursor pode confiar no resultado: `unpreserved` é a única
+ * forma de o item não ter deixado rastro, e ela para o cursor.
+ *
+ * ## Por que SAVEPOINT, e não só `try`
+ *
+ * A ingestão inteira roda numa transação. No PostgreSQL, um comando que falha
+ * **aborta a transação**: daí em diante todo comando devolve `25P02`, inclusive
+ * o INSERT da quarentena. Sem savepoint, o primeiro XML que violasse uma
+ * restrição derrubaria o lote inteiro E impediria a preservação do item que o
+ * derrubou — o pior dos dois mundos. Com savepoint, só a tentativa daquele item
+ * é desfeita, e o que já foi gravado antes dele permanece.
+ */
+async function handleItem(tx, deps, req, adapter, env, doc, now) {
+    let parsed = null;
+    try {
+        parsed = adapter.parse(doc);
+    }
+    catch (err) {
+        return quarantine(tx, req, adapter.source, env, doc, classOf(err), now);
+    }
+    const interpretado = parsed;
+    try {
+        return await tx.savepoint((sp) => interpretado.event
+            ? persistEvent(sp, deps, req, adapter.source, env, doc, interpretado, now)
+            : persistDocument(sp, deps, req, adapter.source, env, doc, interpretado, now));
+    }
+    catch (err) {
+        return quarantine(tx, req, adapter.source, env, doc, classOf(err), now, interpretado);
+    }
+}
+/**
+ * Reprocessa UM item já preservado — sem tocar no cursor.
+ *
+ * ## Por que o cursor fica de fora, e por que isso é a garantia
+ *
+ * O item já está guardado; a posição do provedor já passou por ele há muito
+ * tempo. Mexer no cursor aqui só poderia FAZER MAL: retrocedê-lo republicaria
+ * lotes inteiros, e adiantá-lo pularia itens que ainda não foram vistos. O
+ * reprocessamento é sobre bytes que já temos, e o cursor é sobre bytes que ainda
+ * não pedimos — são eixos independentes.
+ *
+ * ## Idempotência vem do banco, como no caminho normal
+ *
+ * `persistDocument` e `persistEvent` gravam com `ON CONFLICT DO NOTHING` sobre
+ * os índices de deduplicação. Reprocessar dez vezes o mesmo item produz uma
+ * linha e nove `duplicate` — sem `SELECT` prévio, logo sem janela entre
+ * verificar e inserir.
+ */
+export async function reingestPreservedItem(tx, deps, request, doc) {
+    const now = request.now ?? new Date();
+    const env = ENVIRONMENT_MAP[request.environment];
+    const disposition = await handleItem(tx, deps, request, deps.adapter, env, doc, now);
+    switch (disposition.kind) {
+        case 'document_created':
+            return { kind: 'document_created', documentId: disposition.id };
+        case 'document_duplicate':
+            return { kind: 'document_duplicate' };
+        case 'event_applied':
+            return { kind: 'event_applied', eventId: disposition.id };
+        case 'event_pending':
+            return { kind: 'event_pending' };
+        case 'event_duplicate':
+            return { kind: 'event_duplicate' };
+        case 'invalid_preserved':
+        case 'unpreserved':
+            return { kind: 'still_invalid', reason: disposition.reason };
+    }
+}
+/** Classe do motivo. Nunca a mensagem do provedor, nunca trecho de XML. */
+function classOf(err) {
+    if (err instanceof FiscalProviderError) {
+        return err.providerCode ? `${err.errorClass}:${err.providerCode}` : err.errorClass;
+    }
+    return 'unhandled';
+}
+/** Mensagem para a trilha: classe e código, jamais a resposta do provedor. */
+function describeProviderError(err) {
+    return err.providerCode ? `${err.errorClass} (${err.providerCode})` : err.errorClass;
+}
+async function loadCursor(tx, req, source, env) {
+    const rows = await tx `
+    SELECT id, last_nsu, max_nsu, next_attempt_after, consecutive_failures
+      FROM fiscal_sync_cursor
+     WHERE client_id = ${req.clientId} AND source = ${source} AND environment = ${env}
+  `;
+    return rows[0];
+}
+async function saveCursor(tx, req, source, env, next) {
+    // Lote com item não preservado não zera o contador de falhas nem apaga a
+    // classe do erro: quem olha a tela precisa ver que algo ficou para trás.
+    const errorClass = next.preserved ? null : 'transient';
+    await tx `
+    INSERT INTO fiscal_sync_cursor (id, tenant_id, client_id, source, environment,
+                                    last_nsu, max_nsu, last_success_at, next_attempt_after,
+                                    consecutive_failures, last_error_class, updated_at)
+    VALUES (${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env},
+            ${next.lastNsu}, ${next.maxNsu}, ${next.lastSuccessAt}, ${next.nextAttemptAfter},
+            ${next.preserved ? 0 : 1}, ${errorClass}, now())
+    ON CONFLICT (tenant_id, client_id, source, environment)
+    DO UPDATE SET last_nsu = EXCLUDED.last_nsu,
+                  max_nsu = EXCLUDED.max_nsu,
+                  last_success_at = EXCLUDED.last_success_at,
+                  next_attempt_after = EXCLUDED.next_attempt_after,
+                  consecutive_failures = CASE WHEN ${next.preserved} THEN 0
+                                              ELSE fiscal_sync_cursor.consecutive_failures + 1 END,
+                  last_error_class = ${errorClass},
+                  updated_at = now()
+  `;
+}
+/**
+ * Falha do provedor: conta, classifica e — quando a norma manda — recua.
+ *
+ * O cursor NÃO anda. `throttled` e `auth` recebem espera; `transient` recebe
+ * backoff exponencial com teto, porque insistir a cada minuto contra um serviço
+ * paralisado é o comportamento que o 656 existe para punir.
+ */
+async function recordFailure(tx, req, source, env, err, now, cursorBefore, contractVersion) {
+    const backoff = err.retryAfter ?? computeBackoff(err.errorClass, now);
+    await tx `
+    INSERT INTO fiscal_sync_cursor (id, tenant_id, client_id, source, environment,
+                                    last_nsu, next_attempt_after, consecutive_failures,
+                                    last_error_class, updated_at)
+    VALUES (${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env},
+            ${cursorBefore}, ${backoff}, 1, ${err.errorClass}, now())
+    ON CONFLICT (tenant_id, client_id, source, environment)
+    DO UPDATE SET next_attempt_after = ${backoff},
+                  consecutive_failures = fiscal_sync_cursor.consecutive_failures + 1,
+                  last_error_class = ${err.errorClass},
+                  updated_at = now()
+  `;
+    await tx `
+    INSERT INTO fiscal_sync_run (id, tenant_id, client_id, source, environment, outcome,
+                                 cursor_before, cursor_after, error_class, detail,
+                                 contract_version,
+                                 job_name, job_version, lease_id, retryable, retry_after,
+                                 finished_at)
+    VALUES (${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env}, 'provider_error',
+            ${cursorBefore}, ${cursorBefore}, ${err.errorClass},
+            ${describeProviderError(err)},
+            -- A versão do contrato importa MAIS na falha do que no sucesso: um
+            -- PROTOCOL_CONTRACT_MISMATCH só é investigável se a linha disser
+            -- contra qual contrato a resposta foi conferida.
+            ${contractVersion},
+            ${req.job?.name ?? null}, ${req.job?.version ?? null}, ${req.job?.leaseId ?? null},
+            -- Classes "auth" e "not_allowed" não são retentáveis: só uma pessoa
+            -- as resolve, e a trilha precisa dizer isso sem que alguém
+            -- reconstrua a decisão a partir da classe do erro.
+            ${err.errorClass !== 'auth' && err.errorClass !== 'not_allowed'},
+            ${backoff},
+            now())
+  `;
+}
+/** Espera por classe de erro. `auth` é longo porque só uma pessoa o resolve. */
+function computeBackoff(cls, now) {
+    const seconds = cls === 'throttled' ? 3600 : cls === 'auth' ? 3600 : cls === 'not_allowed' ? 3600 : 300;
+    return new Date(now.getTime() + seconds * 1000);
+}
+async function recordRun(tx, req, source, env, report, now, contractVersion) {
+    // Duração MEDIDA, e não zero fixo. O valor constante que estava aqui fazia a
+    // coluna existir sem informar nada — pior do que ausente, porque um painel a
+    // apresentaria como "todo lote leva 0ms".
+    const durationMs = Math.max(0, Date.now() - now.getTime());
+    await tx `
+    INSERT INTO fiscal_sync_run (id, tenant_id, client_id, source, environment, outcome,
+                                 documents_fetched, documents_new, documents_duplicate,
+                                 documents_failed, events_pending, events_applied,
+                                 events_reconciled, cursor_before, cursor_after, error_class,
+                                 detail, contract_version, job_name, job_version, lease_id,
+                                 started_at, finished_at, duration_ms)
+    VALUES (${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env}, ${report.outcome},
+            ${report.documentsFetched}, ${report.documentsNew}, ${report.documentsDuplicate},
+            ${report.documentsFailed}, ${report.eventsPending}, ${report.eventsApplied},
+            ${report.eventsReconciled}, ${report.cursorBefore}, ${report.cursorAfter},
+            ${report.errorClass}, ${report.detail}, ${contractVersion},
+            ${req.job?.name ?? null}, ${req.job?.version ?? null}, ${req.job?.leaseId ?? null},
+            ${now}, now(), ${durationMs})
+  `;
+}
+/**
+ * Guarda o XML original e devolve o `blob`.
+ *
+ * O RAW nunca é reescrito: o que vai para o storage são os bytes que o provedor
+ * entregou, e o sha256 é deles. É esse arquivo que tem valor probatório — o
+ * normalizado é conveniência de leitura, e não substitui o documento.
+ */
+async function persistRaw(tx, deps, req, doc, competenceLabel) {
+    const sha256 = sha256Hex(doc.raw);
+    if (!deps.storage)
+        return null;
+    const key = buildStorageKey({
+        tenantId: req.tenantId,
+        clientId: req.clientId,
+        categoryKey: 'fiscal',
+        documentId: sha256.slice(0, 32),
+        versionNo: 1,
+        competenceLabel: competenceLabel ?? undefined,
+    });
+    // Mesmo conteúdo já guardado = mesmo blob. O sha256 é a identidade, e
+    // reenviar bytes idênticos ao storage é desperdício com risco de divergência.
+    const existing = await tx `
+    SELECT id FROM blob WHERE checksum_sha256 = ${sha256} LIMIT 1
+  `;
+    if (existing[0])
+        return { blobId: existing[0].id, sha256 };
+    await deps.storage.put({ key, body: doc.raw, contentType: doc.mimeType });
+    const blobId = uuidv7();
+    await tx `
+    INSERT INTO blob (id, tenant_id, checksum_sha256, size_bytes, mime_type,
+                      storage_provider, storage_key, av_status)
+    VALUES (${blobId}, ${req.tenantId}, ${sha256}, ${doc.raw.byteLength}, ${doc.mimeType},
+            ${deps.storage.key}, ${key}, 'skipped')
+  `;
+    return { blobId, sha256 };
+}
+async function persistDocument(tx, deps, req, source, env, doc, parsed, _now) {
+    const raw = await persistRaw(tx, deps, req, doc, parsed.competenceLabel ?? null);
+    if (parsed.contentKind === 'full' && !raw) {
+        // Um documento declarado COMPLETO sem o original guardado é uma afirmação
+        // sem lastro — o banco recusa a linha, e recusar aqui devolve um motivo
+        // legível em vez de uma violação de CHECK contada como "documento ilegível".
+        // Sem storage configurado, a ingestão de documento completo não acontece —
+        // mas o item ainda vai para a caixa de entrada, e nada se perde.
+        throw new FiscalProviderError('invalid', 'documento completo exige storage configurado para preservar o XML original', 'RAW_STORAGE_REQUIRED');
+    }
+    // A direção sai do CONFRONTO com o ator consultado, não de um default. Ver
+    // `direction.ts`: `issued` fixo trocava receita por despesa no fechamento.
+    const veredito = classifyFiscalDirection({
+        actorDocument: req.actorDocument,
+        issuerDocument: parsed.issuerDocument,
+        recipientDocument: parsed.recipientDocument,
+        intermediaryDocument: parsed.intermediaryDocument,
+    });
+    const id = uuidv7();
+    const normalized = {
+        ...parsed.normalized,
+        // Como se chegou à direção fica gravado junto: auditar uma classificação
+        // não pode exigir reabrir o XML.
+        directionBasis: veredito.basis,
+    };
+    // `ON CONFLICT DO NOTHING` sobre o índice de deduplicação: a idempotência é
+    // do BANCO, não de um `SELECT` anterior. Dois workers no mesmo lote não
+    // conseguem criar duas notas para o mesmo documento — não há janela entre
+    // verificar e inserir porque não há dois momentos.
+    const inserted = await tx `
+    INSERT INTO fiscal_document (
+      id, tenant_id, client_id, document_type, direction, source, source_environment,
+      source_nsu, access_key, document_number, series, issuer_document, issuer_name,
+      recipient_document, recipient_name, issued_at, competence_label, gross_amount,
+      content_kind, raw_blob_id, raw_sha256, normalized, dedupe_key
+    ) VALUES (
+      ${id}, ${req.tenantId}, ${req.clientId}, ${parsed.documentType}, ${veredito.direction},
+      ${source}, ${env}, ${doc.nsu}, ${parsed.accessKey ?? null},
+      ${parsed.documentNumber ?? null}, ${parsed.series ?? null},
+      ${parsed.issuerDocument ?? null}, ${parsed.issuerName ?? null},
+      ${parsed.recipientDocument ?? null}, ${parsed.recipientName ?? null},
+      ${parsed.issuedAt ?? null}, ${parsed.competenceLabel ?? null},
+      ${parsed.grossAmount ?? null}, ${parsed.contentKind},
+      ${raw?.blobId ?? null}, ${raw?.sha256 ?? null},
+      ${tx.json(normalized)}, ${parsed.dedupeKey}
+    )
+    ON CONFLICT (tenant_id, client_id, dedupe_key) DO NOTHING
+    RETURNING id
+  `;
+    return inserted[0]
+        ? { kind: 'document_created', id: inserted[0].id }
+        : { kind: 'document_duplicate' };
+}
+/**
+ * Evento sobre um documento.
+ *
+ * Cancelar não apaga. A nota permanece, com `status='cancelled'` — ela existiu,
+ * alguém a contabilizou, e some do painel só se uma pessoa decidir escondê-la.
+ *
+ * ## O evento cujo documento ainda não chegou
+ *
+ * O ambiente nacional ordena a distribuição por RECEPÇÃO, não por emissão, e
+ * portanto o evento pode legitimamente vir antes. Ele NÃO é duplicata, não é
+ * erro e não pode ser ignorado: é informação fiscal válida ainda não
+ * reconciliada. Vai para a caixa de entrada com os bytes originais e sai de lá
+ * quando o alvo chegar (`reconcileFiscalPendingEvents`).
+ */
+async function persistEvent(tx, deps, req, source, env, doc, parsed, now) {
+    const ev = parsed.event;
+    // A busca do alvo é por (cliente, chave) — e é essa dupla que impede o evento
+    // de um cliente de alcançar o documento homônimo de outro.
+    const target = await tx `
+    SELECT id FROM fiscal_document
+     WHERE client_id = ${req.clientId} AND access_key = ${ev.targetAccessKey}
+     LIMIT 1
+  `;
+    if (!target[0])
+        return enqueuePendingEvent(tx, req, source, env, doc, parsed, now);
+    const raw = await persistRaw(tx, deps, req, doc, parsed.competenceLabel ?? null);
+    const applied = await applyEventToDocument(tx, req.tenantId, {
+        documentId: target[0].id,
+        eventType: ev.type,
+        eventCode: ev.code ?? null,
+        occurredAt: ev.occurredAt ?? null,
+        sourceNsu: doc.nsu,
+        rawBlobId: raw?.blobId ?? null,
+        payload: parsed.normalized,
+        dedupeKey: parsed.dedupeKey,
+    });
+    return applied.created
+        ? { kind: 'event_applied', id: applied.id }
+        : // Duplicata DE VERDADE: o evento já está gravado sobre este documento.
+            // É o único caso que merece esse nome.
+            { kind: 'event_duplicate' };
+}
+/**
+ * Grava o evento no documento e aplica o efeito de estado.
+ *
+ * Idempotente pelo índice de deduplicação do banco: reprocessar o mesmo evento
+ * não cria segunda linha nem reaplica efeito. Quando o `INSERT` não retorna
+ * nada, o id é buscado — a linha existe, e quem chama precisa dela para marcar
+ * a caixa de entrada como aplicada.
+ */
+async function applyEventToDocument(tx, tenantId, input) {
+    const id = uuidv7();
+    const inserted = await tx `
+    INSERT INTO fiscal_document_event (
+      id, tenant_id, fiscal_document_id, event_type, event_code, occurred_at,
+      source_nsu, raw_blob_id, payload, dedupe_key
+    ) VALUES (
+      ${id}, ${tenantId}, ${input.documentId}, ${input.eventType}, ${input.eventCode},
+      ${input.occurredAt}, ${input.sourceNsu}, ${input.rawBlobId},
+      ${tx.json(input.payload)}, ${input.dedupeKey}
+    )
+    ON CONFLICT (tenant_id, fiscal_document_id, dedupe_key) DO NOTHING
+    RETURNING id
+  `;
+    if (!inserted[0]) {
+        const [existing] = await tx `
+      SELECT id FROM fiscal_document_event
+       WHERE fiscal_document_id = ${input.documentId} AND dedupe_key = ${input.dedupeKey}
+       LIMIT 1
+    `;
+        return { created: false, id: existing.id };
+    }
+    if (input.eventType === 'cancellation') {
+        await tx `UPDATE fiscal_document SET status = 'cancelled', updated_at = now()
+              WHERE id = ${input.documentId}`;
+    }
+    else if (input.eventType === 'replacement') {
+        await tx `UPDATE fiscal_document SET status = 'replaced', updated_at = now()
+              WHERE id = ${input.documentId}`;
+    }
+    return { created: true, id: inserted[0].id };
+}
+/**
+ * Guarda o evento que ainda não tem alvo.
+ *
+ * Os BYTES vão inteiros para a linha, e não para o storage. Não é economia: é
+ * a única forma de a preservação e o avanço do cursor acontecerem na MESMA
+ * transação. Com o RAW num objeto externo existiria a janela entre o `PUT` e o
+ * commit — e uma janela nesse ponto é exatamente o defeito que esta correção
+ * fecha.
+ */
+async function enqueuePendingEvent(tx, req, source, env, doc, parsed, _now) {
+    const ev = parsed.event;
+    const inserted = await tx `
+    INSERT INTO fiscal_ingestion_inbox (
+      id, tenant_id, client_id, source, source_environment, source_nsu, state,
+      document_type, event_type, event_code, event_sequence, occurred_at,
+      target_access_key, raw, raw_sha256, normalized, dedupe_key
+    ) VALUES (
+      ${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env}, ${doc.nsu},
+      'pending_target', ${parsed.documentType}, ${ev.type}, ${ev.code ?? null},
+      ${ev.sequence ?? null}, ${ev.occurredAt ?? null}, ${ev.targetAccessKey},
+      ${Buffer.from(doc.raw)}, ${sha256Hex(doc.raw)},
+      ${tx.json(parsed.normalized)}, ${parsed.dedupeKey}
+    )
+    ON CONFLICT (tenant_id, client_id, dedupe_key) DO NOTHING
+    RETURNING id
+  `;
+    // Sem linha nova, o evento JÁ estava guardado (ou já foi aplicado): a
+    // deduplicação é do banco, não de memória, e sobrevive a replay e a crash.
+    return inserted[0] ? { kind: 'event_pending' } : { kind: 'event_duplicate' };
+}
+/**
+ * Guarda o item que não pôde ser interpretado.
+ *
+ * `invalid` não é "descartado": os bytes ficam, com o NSU e a classe do motivo,
+ * e é isso que permite a recuperação pontual (`consNSU`) sem pedir nada ao
+ * provedor. Se nem esta gravação for possível, o item é declarado NÃO
+ * preservado e o cursor para — a única saída honesta.
+ */
+async function quarantine(tx, req, source, env, doc, reason, _now, parsed) {
+    const sha = sha256Hex(doc.raw);
+    try {
+        await tx.savepoint((sp) => sp `
+      INSERT INTO fiscal_ingestion_inbox (
+        id, tenant_id, client_id, source, source_environment, source_nsu, state,
+        document_type, event_type, event_code, event_sequence, occurred_at,
+        target_access_key, raw, raw_sha256, normalized, reject_reason, dedupe_key
+      ) VALUES (
+        ${uuidv7()}, ${req.tenantId}, ${req.clientId}, ${source}, ${env}, ${doc.nsu},
+        'invalid', ${parsed?.documentType ?? null}, ${null}, ${null}, ${null}, ${null},
+        ${null}, ${Buffer.from(doc.raw)}, ${sha}, ${tx.json({})},
+        ${reason}, ${`raw:${sha}`}
+      )
+      ON CONFLICT (tenant_id, client_id, dedupe_key) DO NOTHING
+    `);
+        return { kind: 'invalid_preserved', reason };
+    }
+    catch {
+        return { kind: 'unpreserved', reason };
+    }
+}
+/**
+ * Aplica os eventos guardados cujo documento-alvo já existe.
+ *
+ * ## O `JOIN` é a prova de isolamento
+ *
+ * A junção é por `(tenant_id, client_id, access_key)`. Um evento do Cliente A
+ * não alcança o documento do Cliente B mesmo com a MESMA chave de acesso, e
+ * nenhum evento atravessa escritórios — antes da RLS, que fecha por cima.
+ *
+ * ## A ordem importa
+ *
+ * Dois eventos sobre a mesma nota (cancelamento e depois análise fiscal, por
+ * exemplo) mudam o estado final conforme a sequência. Aplicar na ordem de
+ * ocorrência, com o NSU e a sequência do leiaute como desempate, é o que faz o
+ * resultado da reconciliação ser igual ao de tê-los recebido em ordem.
+ *
+ * Exportada porque um varredor futuro precisa dela sem repetir a lógica.
+ */
+export async function reconcileFiscalPendingEvents(tx, _deps, req) {
+    const pendentes = await tx `
+    SELECT i.id, d.id AS document_id, i.event_type, i.event_code, i.occurred_at,
+           i.source_nsu, i.normalized, i.dedupe_key
+      FROM fiscal_ingestion_inbox i
+      JOIN fiscal_document d
+        ON d.tenant_id = i.tenant_id
+       AND d.client_id = i.client_id
+       AND d.access_key = i.target_access_key
+     WHERE i.client_id = ${req.clientId}
+       AND i.state = 'pending_target'
+     ORDER BY i.occurred_at NULLS LAST,
+              CASE WHEN i.source_nsu ~ '^[0-9]+$' THEN i.source_nsu::numeric END NULLS LAST,
+              CASE WHEN i.event_sequence ~ '^[0-9]+$' THEN i.event_sequence::numeric END NULLS LAST,
+              i.received_at
+  `;
+    let aplicados = 0;
+    for (const p of pendentes) {
+        try {
+            // Um savepoint por evento: um pendente problemático não pode desfazer a
+            // reconciliação dos outros nem abortar o lote que acabou de ser gravado.
+            // Ele simplesmente CONTINUA pendente, e a próxima varredura tenta de novo.
+            await tx.savepoint(async (sp) => {
+                const resultado = await applyEventToDocument(sp, req.tenantId, {
+                    documentId: p.document_id,
+                    eventType: p.event_type,
+                    eventCode: p.event_code,
+                    occurredAt: p.occurred_at,
+                    sourceNsu: p.source_nsu,
+                    // O blob do evento reconciliado fica nulo: os bytes originais
+                    // continuam na caixa de entrada, que é onde foram preservados.
+                    // Duplicá-los no storage não acrescentaria garantia nenhuma.
+                    rawBlobId: null,
+                    payload: p.normalized,
+                    dedupeKey: p.dedupe_key,
+                });
+                // `applied` mesmo quando o evento já existia: o que a caixa registra é
+                // que este item saiu da espera, não que ele criou a linha.
+                await sp `
+          UPDATE fiscal_ingestion_inbox
+             SET state = 'applied', applied_at = now(), applied_event_id = ${resultado.id}
+           WHERE id = ${p.id}
+        `;
+            });
+            aplicados += 1;
+        }
+        catch {
+            // Segue pendente. Nada é perdido, e a caixa de entrada mostra a idade.
+        }
+    }
+    return aplicados;
+}
+//# sourceMappingURL=pipeline.js.map