release(financial): NSA por convênio, Pix por chave e o ciclo de vida da conta-cedente

package.json

@@ -39,7 +39,6 @@
     "docs:links": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/handbook/link-scan.ts",
     "wiki:sync": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/handbook/wiki-sync.ts",
     "cnab:index": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/financial/cnab-manual-index.ts",
-    "cnab:ispb": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/financial/build-ispb-map.ts",
     "logbook": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/claude/logbook.ts",
     "release:notes": "node --experimental-strip-types --enable-source-maps --no-warnings scripts/ci/release-notes.ts",
     "audit": "pnpm audit --prod --audit-level=high",

scripts/ci/test-integration.ts

@@ -145,6 +145,11 @@ const SUITES: Readonly<Record<string, Suite>> = {
     // Alocação de NSA sob concorrência real: prova que o SELECT ... FOR UPDATE serializa e que dois
     // pedidos simultâneos nunca recebem o mesmo número. NSA repetido = retransmissão para o banco.
     'tests/modules/financial/adapters/persistence/nsa-allocation.drizzle-mysql.test.ts',
+    // Backfill da migration 0057 (#943, CA4): a sequência de cada convênio nasce em MAX(next_nsa).
+    // ⚠️ Existe porque as migrations rodam contra banco VAZIO no `before` de cada arquivo — um
+    // `INSERT … SELECT` sobre tabela vazia passa sem inserir nada. Em produção ela roda sobre contas
+    // reais, no job de migration, ANTES de o app subir: falhar ali derruba o deploy.
+    'tests/modules/financial/adapters/persistence/convenio-nsa-backfill.drizzle-mysql.test.ts',
     // Remessa (migration 0044): cabeçalho + vínculos na mesma transação, anti-join de documento
     // preso no BANCO, e os UNIQUEs de NSA-por-conta e nome de arquivo.
     'tests/modules/financial/adapters/persistence/remittance-repository.drizzle-mysql.test.ts',

scripts/etl/financial/mapper.ts

@@ -12,6 +12,7 @@
 
 import { type Result, ok, err } from '#src/shared/primitives/result.ts';
 import type { DocumentType, PaymentMethod } from '#src/modules/financial/domain/document/types.ts';
+import { splitCheckDigit } from '#src/modules/financial/domain/payout/payee-account.ts';
 import type { LegacyAccountRow, LegacyPayableRow } from '../legacy/rows.ts';
 import type { QuarantineReason } from '../quarantine/reason.ts';
 import { EXCLUDED_PAYABLE_LEGACY_IDS } from './exclusions.ts';
@@ -28,6 +29,8 @@ export type CedenteAccountPlan = Readonly<{
   input: Readonly<{
     bankCode: string;
     agency: string;
+    // #856 — o DV da agência, separado do número. Ausente quando o legado não trazia separador.
+    agencyDigit?: string;
     accountNumber: string;
     accountDigit: string;
     convenio: string;
@@ -54,15 +57,32 @@ export const mapLegacyAccountRow = (
     errors.push({ tag: 'EnumUnknown', field: 'bank', attempted: row.bank });
   }
 
+  // F7: a agência legada vem com o DV EMBUTIDO, no formato `NNNN-D`.
+  //
+  // ⚠️ ELA ERA GRAVADA INTEIRA, e isso corrompia toda remessa daquela conta em silêncio (#856). O
+  // emissor escreve `digits(agency, 5)`, que faz `replace(/\D/g,'')` antes do pad: `1234-5` virava
+  // `12345` nas posições 053-057, onde o banco espera `01234`. Cinco dígitos, cabe no campo, nenhum
+  // gate acusa — e o arquivo vai ao banco apontando outra agência. O comentário anterior dizia que o
+  // dígito ia "no campo próprio"; não ia, porque campo próprio não existia. Agora existe.
+  //
+  // A decomposição é `splitCheckDigit`, do domínio — a MESMA que lê a conta do favorecido. Uma
+  // segunda gramática aqui divergiria da de lá no dia em que uma das duas mudasse.
+  // ⚠️ O QUE NÃO DECOMPÕE NÃO VAI PARA QUARENTENA, e a escolha é a lição da #879. A conta-cedente
+  // serve à CONCILIAÇÃO sem agência válida; barrar a migração por um campo que só a remessa exige
+  // repetiria o beco do `'LEGADO'` — conta ausente do sistema, sem via de correção pela tela. Segue
+  // como veio, e quem recusa é `checkCedenteAgency` na hora de gerar, com lacuna nomeada, mensagem
+  // PT-BR dizendo onde corrigir, e ANTES de queimar NSA.
+  const agencyParts = splitCheckDigit(row.agency.trim());
+
   if (errors.length > 0 || bankCode === undefined) return err(errors);
 
   return ok({
     legacyId: row.id,
     input: {
       bankCode,
-      // F7: agência legada vem com DV embutido ('0288-7') E dv separado — preservamos
-      // a agência como veio (domínio só exige não-blank) e o dv no campo próprio.
-      agency: row.agency,
+      agency: agencyParts?.base ?? row.agency,
+      // `null` é "o legado não trouxe DV", e vira ausência — nunca `'0'`, que é um dígito afirmado.
+      ...(agencyParts?.digit != null ? { agencyDigit: agencyParts.digit } : {}),
       accountNumber: row.accountNumber,
       accountDigit: row.dv,
       // D6: o convênio real do Bradesco não existe no legado, e o correto é nascer VAZIO.

src/modules/financial/adapters/cnab/bradesco-multipag-translator.ts

@@ -46,10 +46,8 @@ const translateErrorFor = (error: RemittanceFileError): CnabTranslateError => {
     // no campo — não "falhou a tradução" (#838).
     case 'pix-key-unrepresentable':
       return 'cnab-pix-key-unrepresentable';
-    // Os dois erros de TRADUÇÃO da rota Pix. Sobem nomeados pela mesma régua: um manda ao cadastro
-    // (ou à fonte do Bacen), o outro diz que o tipo da chave não existe no domínio do layout.
-    case 'payee-ispb-unknown':
-      return 'cnab-payee-ispb-unknown';
+    // O erro de TRADUÇÃO da rota Pix, que sobe nomeado: diz que o tipo da chave não existe no
+    // domínio do layout. Eram dois até a #923 — o `payee-ispb-unknown` saiu com a tabela de-para.
     case 'remittance-pix-key-type-unsupported':
       return 'cnab-pix-key-type-unsupported';
     // `remittance-mixed-file-modalities` converge para o desfecho genérico, e é escolha, não