@baruk/core 0.3.1 → 0.5.0

package/dist/cjs/communication/claim.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Reserva atômica do direito de enviar.
+ *
+ * O desenho anterior era, em substância:
+ *
+ *     alreadySent(key)  →  adapter.send()  →  markSent(key)
+ *
+ * Três passos, e o intervalo entre o primeiro e o terceiro é uma janela aberta:
+ * dois workers que perguntam "já enviei?" ao mesmo tempo recebem "não" os dois,
+ * e os dois chamam o provider. O cliente recebe a mesma cobrança duas vezes. A
+ * marcação posterior não conserta nada — o dinheiro do envio já saiu, e a
+ * mensagem também.
+ *
+ * Aqui a ordem é outra:
+ *
+ *     claim(key)  →  markProviderAttempt  →  [só o vencedor] send()  →  settle
+ *
+ * `claim` é uma operação ÚNICA e atômica no armazenamento: ou ela devolve a
+ * reserva, ou devolve o motivo de não ter devolvido. Não existe estado
+ * intermediário observável entre "verifiquei" e "reservei", porque não há dois
+ * momentos. Quem não ganhou a reserva não chama o provider — nem para "tentar de
+ * novo mais rápido".
+ *
+ * **A reserva vem ANTES do efeito externo, e essa é a regra inteira.** Qualquer
+ * proteção que aconteça depois de `send` é contabilidade do que já foi feito,
+ * não controle.
+ *
+ * ## O que a H2 acrescentou, e por quê
+ *
+ * A reserva tem prazo, porque processo morre segurando reserva e uma etapa calada
+ * para sempre é pior que uma duplicata rara. Mas retomar por prazo vencido, do
+ * jeito que estava, era retomar **às cegas**: o motor não tinha como distinguir
+ *
+ *   (a) o titular anterior morreu ANTES de falar com o provider — nada saiu, e
+ *       reenviar é obviamente certo;
+ *   (b) o titular anterior morreu DEPOIS de falar com o provider — pode ter saído,
+ *       e reenviar duplica.
+ *
+ * Os dois casos chegavam aqui com a mesma cara. `markProviderAttempt` é o que os
+ * separa: uma marca durável, gravada IMEDIATAMENTE antes da chamada externa, em
+ * fronteira própria. Quem retoma uma reserva que já tinha essa marca sabe que o
+ * desfecho é **desconhecido**, não "não enviado" — e desconhecido não autoriza
+ * reenvio cego.
+ *
+ * A marca é conservadora de propósito: gravar antes de chamar significa que um
+ * processo que morre entre a marca e a chamada é classificado como "pode ter
+ * enviado" quando não enviou. Erra para o lado de calar uma mensagem, nunca para
+ * o lado de mandar duas.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CLAIM_TTL_MS = void 0;
+exports.createInMemoryDispatchClaimStore = createInMemoryDispatchClaimStore;
+/** Prazo da reserva. Ver `createInMemoryDispatchClaimStore` para o raciocínio. */
+exports.DEFAULT_CLAIM_TTL_MS = 10 * 60 * 1000;
+/**
+ * Reserva em memória — **um processo só**.
+ *
+ * Serve a testes e a consumidores que rodam em instância única. Não serve a
+ * produção com mais de um worker, e a limitação está aqui em vez de num
+ * comentário do consumidor porque é o consumidor que erra: "por enquanto é uma
+ * instância" é verdade até o dia do primeiro redeploy com sobreposição.
+ *
+ * É atômica dentro do processo porque a decisão inteira acontece sem `await` no
+ * meio — em JavaScript isso basta para que dois `dispatch` concorrentes não se
+ * intercalem no ponto de decisão. Essa propriedade é o que o teste de
+ * concorrência in-process exercita; a prova de múltiplos processos é do store
+ * SQL.
+ *
+ * O prazo (`ttlMs`) existe pela mesma razão do store SQL: processo que morre
+ * segurando reserva não pode calar a etapa para sempre. Dez minutos é muito
+ * maior que qualquer timeout de provider (o mais longo aqui é 10 s) e muito
+ * menor que o intervalo entre ciclos da régua (24 h).
+ */
+function createInMemoryDispatchClaimStore(options = {}) {
+    const ttl = options.ttlMs ?? exports.DEFAULT_CLAIM_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const entries = new Map();
+    let seq = 0;
+    const write = async (entry, event) => {
+        if (!options.audit)
+            return;
+        await options.audit.record({
+            kind: event.kind,
+            ctx: entry.req.ctx,
+            channel: entry.req.channel,
+            eventType: entry.req.eventType,
+            subjectRef: entry.req.subjectRef,
+            recipientRef: entry.req.recipientRef,
+            idempotencyKey: entry.req.idempotencyKey,
+            providerRef: event.providerRef ?? null,
+            skipReason: event.skipReason ?? null,
+            status: event.status ?? null,
+            code: event.code ?? null,
+            detail: event.detail ?? null,
+            attempt: entry.attempt,
+        });
+    };
+    return {
+        async claim(req) {
+            // NENHUM `await` daqui até o `entries.set`. Um `await` aqui reabriria
+            // exatamente a janela que este módulo existe para fechar.
+            const current = entries.get(req.idempotencyKey);
+            const at = now();
+            if (current) {
+                if (current.state === 'sent')
+                    return { granted: false, reason: 'already_sent' };
+                if (current.state === 'failed_permanent') {
+                    return { granted: false, reason: 'permanently_failed' };
+                }
+                if (current.state === 'unknown_outcome') {
+                    return {
+                        granted: false,
+                        reason: 'unknown_outcome',
+                        detail: 'desfecho da tentativa anterior é desconhecido',
+                    };
+                }
+                if (current.state === 'in_flight' && current.expiresAt > at) {
+                    return { granted: false, reason: 'in_flight' };
+                }
+            }
+            const attempt = (current?.attempt ?? 0) + 1;
+            const recovered = current?.state === 'in_flight' && current.expiresAt <= at;
+            const providerAttempts = current?.providerAttempts ?? 0;
+            const claimId = current?.claimId ?? `mem-${++seq}`;
+            const claimToken = `tok-${++seq}`;
+            const entry = {
+                claimId,
+                claimToken,
+                state: 'in_flight',
+                attempt,
+                expiresAt: at + ttl,
+                providerAttempts,
+                providerFirstAttemptAt: current?.providerFirstAttemptAt ?? null,
+                req,
+            };
+            entries.set(req.idempotencyKey, entry);
+            const claim = {
+                claimId,
+                claimToken,
+                idempotencyKey: req.idempotencyKey,
+                attempt,
+                recoveredFromExpiredClaim: recovered,
+                // Retomada só é DESCONHECIDA se o titular anterior chegou a falar com o
+                // provider. Recuperar uma reserva que morreu antes disso é seguro, e
+                // tratá-la como desconhecida calaria a etapa sem motivo.
+                previousAttemptReachedProvider: recovered && providerAttempts > 0,
+                providerFirstAttemptAgeMs: entry.providerFirstAttemptAt === null ? null : at - entry.providerFirstAttemptAt,
+            };
+            await write(entry, {
+                kind: 'dispatch_claimed',
+                code: claim.previousAttemptReachedProvider
+                    ? 'recovered_unknown_outcome'
+                    : recovered
+                        ? 'recovered_from_expired_claim'
+                        : null,
+            });
+            return { granted: true, claim };
+        },
+        async markProviderAttempt(claim) {
+            const current = entries.get(claim.idempotencyKey);
+            // Linha sumiu, ou a geração é outra: quem chamou perdeu a reserva. A marca
+            // NÃO é gravada — gravá-la contaria uma tentativa externa do titular atual
+            // para o zumbi, e a próxima retomada leria o número errado.
+            if (!current || current.claimToken !== claim.claimToken) {
+                return { authority: 'lost', detail: 'reserva retomada por outra execução' };
+            }
+            if (current.state !== 'in_flight') {
+                return {
+                    authority: 'already_final',
+                    state: current.state,
+                    detail: `chave já assentada como ${current.state}`,
+                };
+            }
+            current.providerAttempts += 1;
+            current.providerFirstAttemptAt = current.providerFirstAttemptAt ?? now();
+            return { authority: 'held' };
+        },
+        async settle(claim, outcome, event) {
+            const current = entries.get(claim.idempotencyKey);
+            // Reserva já tomada por outro (prazo vencido): quem perdeu o direito não
+            // assenta o desfecho. A comparação é pelo TOKEN da geração, não pelo id da
+            // linha — o id sobrevive à retomada, o token não.
+            if (!current || current.claimToken !== claim.claimToken)
+                return;
+            if (outcome.kind === 'sent') {
+                current.state = 'sent';
+            }
+            else if (outcome.kind === 'failed') {
+                current.state = outcome.permanent ? 'failed_permanent' : 'failed_retryable';
+                current.expiresAt = 0;
+            }
+            else if (outcome.kind === 'unknown') {
+                current.state = 'unknown_outcome';
+                current.expiresAt = 0;
+            }
+            else {
+                // `released`: a chave volta a estar livre, sem contar como falha. O
+                // `attempt` permanece — é histórico, e serve para ver insistência.
+                current.state = 'failed_retryable';
+                current.expiresAt = 0;
+            }
+            await write(current, event);
+        },
+        async peek(idempotencyKey) {
+            const current = entries.get(idempotencyKey);
+            if (!current)
+                return 'none';
+            if (current.state === 'in_flight' && current.expiresAt <= now())
+                return 'failed_retryable';
+            return current.state;
+        },
+        async resolveUnknownOutcome(idempotencyKey, resolution, detail) {
+            const current = entries.get(idempotencyKey);
+            if (!current || current.state !== 'unknown_outcome')
+                return;
+            current.state = resolution === 'sent' ? 'sent' : 'failed_retryable';
+            current.expiresAt = 0;
+            await write(current, {
+                kind: resolution === 'sent' ? 'dispatch_sent' : 'dispatch_failed',
+                status: resolution === 'sent' ? 'sent' : null,
+                code: `unknown_resolved_${resolution}`,
+                detail: detail ?? null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=claim.js.map

package/dist/cjs/communication/claim.js.map

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

package/dist/cjs/communication/clearance.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLEARANCE_NOT_REQUIRED = void 0;
+/**
+ * Loja que libera tudo — para fluxos em que o destinatário **é** o remetente.
+ *
+ * O caso legítimo: notificação para a equipe do próprio escritório, teste de
+ * canal para o endereço de quem está configurando, ensaio sem envio. Ali não há
+ * terceiro a proteger, e exigir liberação seria cerimônia sem objeto.
+ *
+ * Existe com nome explícito, e não como default do motor, para que usá-la seja
+ * uma escolha visível na chamada em vez de o que acontece quando alguém
+ * esquece.
+ */
+exports.CLEARANCE_NOT_REQUIRED = {
+    find: async () => ({ cleared: true, clearedAt: null }),
+};
+//# sourceMappingURL=clearance.js.map

package/dist/cjs/communication/clearance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearance.js","sourceRoot":"","sources":["../../../src/communication/clearance.ts"],"names":[],"mappings":";;;AA2CA;;;;;;;;;;GAUG;AACU,QAAA,sBAAsB,GAA4B;IAC7D,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;CACvD,CAAC"}

package/dist/cjs/communication/consent.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Permissão de contato por canal.
+ *
+ * O motor implementa o MECANISMO (registrar, consultar, recusar). A POLÍTICA —
+ * o que fazer quando ninguém decidiu ainda — é do produto, porque a resposta
+ * depende da relação: um escritório cobrando honorário de cliente contratado
+ * não está na mesma posição de quem manda promoção para uma lista.
+ *
+ * O que o motor não faz, em nenhuma configuração: inventar consentimento.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateConsent = evaluateConsent;
+/**
+ * `denied` é absoluto.
+ *
+ * Nenhuma política do produto reverte um opt-out — não há parâmetro para isso, e
+ * é deliberado. Um `denied` vindo de `customer_reply` (o cliente respondeu SAIR
+ * no WhatsApp) é o registro mais forte que existe no sistema, e o dia em que
+ * alguém puder configurar "ignorar opt-out para cobrança" é o dia em que a
+ * configuração vai estar ligada em algum tenant.
+ */
+function evaluateConsent(channel, record, policy = {}) {
+    if (record?.state === 'denied') {
+        return {
+            allowed: false,
+            reason: 'opted_out',
+            detail: `destinatário recusou o canal ${channel}`,
+        };
+    }
+    if (record?.state === 'granted')
+        return { allowed: true };
+    // Sem registro, ou registro `unknown`: a política do produto decide.
+    const onUnknown = policy.onUnknown?.[channel] ?? 'fail_safe';
+    if (onUnknown === 'allow')
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: 'consent_unknown',
+        detail: `sem permissão registrada para ${channel}`,
+    };
+}
+//# sourceMappingURL=consent.js.map

package/dist/cjs/communication/consent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.js","sourceRoot":"","sources":["../../../src/communication/consent.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AA+CH,0CAwBC;AAjCD;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAC7B,OAAmB,EACnB,MAA4B,EAC5B,SAAwB,EAAE;IAE1B,IAAI,MAAM,EAAE,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,WAAW;YACnB,MAAM,EAAE,gCAAgC,OAAO,EAAE;SAClD,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,EAAE,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAE1D,qEAAqE;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,IAAI,WAAW,CAAC;IAC7D,IAAI,SAAS,KAAK,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAEpD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,iBAAiB;QACzB,MAAM,EAAE,iCAAiC,OAAO,EAAE;KACnD,CAAC;AACJ,CAAC"}

package/dist/cjs/communication/context.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Contexto de toda operação de comunicação do ecossistema.
+ *
+ * Existe porque o motor é UM e os consumidores são vários. Sem contexto
+ * explícito, "envie esta mensagem" é ambíguo em três dimensões que só aparecem
+ * quando já é tarde: de qual escritório, sob qual marca, com qual número.
+ *
+ * Nenhum campo tem valor padrão, e nenhum é inferido do ambiente. Um default
+ * aqui seria a porta pela qual um produto envia com a identidade de outro — e
+ * seria justamente no caso que ninguém testou, porque o caminho feliz sempre
+ * passa o contexto certo.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateContext = validateContext;
+exports.contextRef = contextRef;
+const SLUG = /^[a-z][a-z0-9-]{1,62}[a-z0-9]$/;
+/**
+ * Valida o contexto na BORDA do motor.
+ *
+ * Rejeitar aqui, e não no adapter, é o que garante que nenhum caminho de envio
+ * exista sem contexto: o adapter recebe um contexto já validado ou não é
+ * chamado. Um adapter que valida por conta própria é um adapter que pode
+ * esquecer.
+ */
+function validateContext(ctx) {
+    if (!ctx.tenantId || !ctx.tenantId.trim())
+        return 'tenant';
+    if (!SLUG.test(ctx.product))
+        return 'product';
+    if (!SLUG.test(ctx.brand))
+        return 'brand';
+    return null;
+}
+/**
+ * Forma canônica do contexto para chave e trilha: `tenant/product/brand`.
+ *
+ * Não é PII e não é segredo — é o que aparece em log e em métrica, e é o que
+ * permite atribuir custo por tenant, produto e marca depois, sem que nada
+ * precise ser reinstrumentado.
+ */
+function contextRef(ctx) {
+    return `${ctx.tenantId}/${ctx.product}/${ctx.brand}`;
+}
+//# sourceMappingURL=context.js.map

package/dist/cjs/communication/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/communication/context.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAkCH,0CAKC;AASD,gCAEC;AAnCD,MAAM,IAAI,GAAG,gCAAgC,CAAC;AAW9C;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,GAAyB;IACvD,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC3D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,GAAyB;IAClD,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;AACvD,CAAC"}

package/dist/cjs/communication/credentials.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Resolução de credencial de canal — do NOME lógico ao segredo.
+ *
+ * **O motor nunca vê o segredo antes da borda do adapter.** O que atravessa o
+ * domínio é `credentialRef`, um nome; o valor só é materializado no último
+ * passo, e a trava por conta (`credentialResolverFor`) garante que o adapter só
+ * consiga abrir a referência DAQUELA conta.
+ *
+ * O que muda nesta fase é de onde o valor vem.
+ *
+ * O resolvedor anterior traduzia um punhado de nomes fixos de variável de
+ * ambiente. Isso funciona para um tenant e falha de duas maneiras para dois:
+ * ou os dois apontam para o mesmo nome e COMPARTILHAM o token — a WABA de uma
+ * marca respondendo pelo comportamento de outra —, ou apontam para nomes
+ * distintos e nenhum resolve. Nenhuma das duas é aceitável num canal em que o
+ * bloqueio se propaga.
+ *
+ * A saída não é uma tabela nova de segredos: o ecossistema já tem o Vault
+ * Engine (migração 0012) — AES-256-GCM, chave-mestra fora do banco, tenant como
+ * dado autenticado adicional da cifra, RLS FORCE, vencimento e rotação. Um
+ * segundo cofre seria um segundo lugar para errar.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChannelCredentialResolver = createChannelCredentialResolver;
+exports.isVaultRef = isVaultRef;
+exports.isAcceptableForNewBinding = isAcceptableForNewBinding;
+exports.noCredentialResolver = noCredentialResolver;
+/** Esquema das referências que apontam para o cofre. */
+const VAULT_SCHEME = 'vault://';
+/**
+ * Nomes de variável de ambiente ainda aceitos — **legado, em remoção**.
+ *
+ * `RESEND_API_KEY` continua porque a SC entrega e-mail em produção por ela
+ * hoje, e desligá-la para exigir configuração por escritório pararia a régua de
+ * quem está cobrando agora. Removê-la não é hardening, é interrupção de serviço.
+ *
+ * `WHATSAPP_ACCESS_TOKEN` e `SMS_API_KEY` **saíram**. Nenhum tenant os usa —
+ * não há canal de telefone configurado em lugar nenhum —, então a remoção não
+ * quebra nada e fecha a porta antes de o primeiro tenant entrar por ela. Um
+ * token global de WhatsApp que "ainda ninguém usa" é exatamente o tipo de
+ * conveniência que vira padrão no dia em que alguém tem pressa.
+ *
+ * @deprecated Novos tenants devem usar `vault://`. Plano de remoção: quando a
+ * credencial de e-mail da plataforma migrar para o cofre, esta lista some junto
+ * com esta função.
+ */
+const LEGACY_ENV_NAMES = new Set(['RESEND_API_KEY']);
+/** Canais para os quais uma referência de ambiente nunca é aceitável. */
+const ENV_FORBIDDEN_PREFIXES = ['WHATSAPP_', 'SMS_', 'META_'];
+/**
+ * Resolvedor composto: cofre primeiro, ambiente só para o legado declarado.
+ *
+ * A ordem importa e é fixa. Se o ambiente viesse primeiro, uma variável com o
+ * nome certo passaria na frente do cofre do tenant sem que ninguém percebesse —
+ * e o sintoma seria o pior possível: envio bem-sucedido, pela conta errada.
+ */
+function createChannelCredentialResolver(tenantId, secrets, env = process.env) {
+    return async (ref) => {
+        const trimmed = ref?.trim() ?? '';
+        if (!trimmed)
+            return undefined;
+        if (trimmed.startsWith(VAULT_SCHEME)) {
+            if (!secrets)
+                return undefined;
+            const name = trimmed.slice(VAULT_SCHEME.length).trim();
+            // Um nome vazio depois do esquema resolveria para "qualquer coisa" na
+            // implementação errada do store. Recusa antes de chegar lá.
+            if (!name)
+                return undefined;
+            return secrets.reveal(tenantId, name);
+        }
+        // A partir daqui é o caminho legado, e ele é fechado por allowlist de NOME.
+        // Filtrar por "o que parece segredo" deixaria `DATABASE_URL` passar inteiro,
+        // e `credentialRef` é editável por quem administra o escritório.
+        const name = trimmed.split('/').pop() ?? '';
+        if (ENV_FORBIDDEN_PREFIXES.some((p) => name.startsWith(p)))
+            return undefined;
+        if (!LEGACY_ENV_NAMES.has(name))
+            return undefined;
+        return env[name];
+    };
+}
+/**
+ * A referência aponta para o cofre?
+ *
+ * Usado por guard e por tela: um vínculo novo com referência de ambiente é
+ * dívida sendo criada, e deve ser visível no momento do cadastro, não seis meses
+ * depois.
+ */
+function isVaultRef(ref) {
+    return typeof ref === 'string' && ref.trim().startsWith(VAULT_SCHEME);
+}
+/**
+ * Referência aceitável para um vínculo NOVO?
+ *
+ * `NO_GLOBAL_WHATSAPP_CREDENTIAL_FOR_NEW_TENANTS` deixa de ser promessa de
+ * documento e vira predicado que um teste consegue exercer.
+ */
+function isAcceptableForNewBinding(channel, ref) {
+    if (channel === 'whatsapp' || channel === 'sms')
+        return isVaultRef(ref);
+    return isVaultRef(ref) || LEGACY_ENV_NAMES.has((ref ?? '').split('/').pop() ?? '');
+}
+/**
+ * Resolvedor que não abre NADA — nem cofre, nem ambiente.
+ *
+ * Existe para as composições que montam o motor só para LER configuração
+ * (quais canais estão registrados, qual o remetente, qual o `credentialRef`) e
+ * nunca despacham. `GET /v1/communication/channels` é exatamente esse caso.
+ *
+ * Passar o resolvedor de envio ali seria dar à rota de leitura a capacidade de
+ * decifrar, ainda que ela não a exerça hoje. Capacidade que não é exercida é
+ * capacidade que alguém exerce depois, na primeira mudança que parecer
+ * inofensiva — e a diferença entre "não usa" e "não pode" é a única que sobrevive
+ * a essa mudança.
+ */
+function noCredentialResolver() {
+    return async () => undefined;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/cjs/communication/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../../src/communication/credentials.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AAiDH,0EA0BC;AASD,gCAEC;AAQD,8DAGC;AAeD,oDAEC;AAjGD,wDAAwD;AACxD,MAAM,YAAY,GAAG,UAAU,CAAC;AAEhC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;AAE1E,yEAAyE;AACzE,MAAM,sBAAsB,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,SAAgB,+BAA+B,CAC7C,QAAgB,EAChB,OAAiC,EACjC,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,KAAK,EAAE,GAAW,EAA+B,EAAE;QACxD,MAAM,OAAO,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAE/B,IAAI,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,OAAO;gBAAE,OAAO,SAAS,CAAC;YAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACvD,sEAAsE;YACtE,4DAA4D;YAC5D,IAAI,CAAC,IAAI;gBAAE,OAAO,SAAS,CAAC;YAC5B,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,4EAA4E;QAC5E,6EAA6E;QAC7E,iEAAiE;QACjE,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAC5C,IAAI,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7E,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,SAAS,CAAC;QAClD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,GAAW;IACpC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACxE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,OAAe,EAAE,GAAW;IACpE,IAAI,OAAO,KAAK,UAAU,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;IACxE,OAAO,UAAU,CAAC,GAAG,CAAC,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB;IAClC,OAAO,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC;AAC/B,CAAC"}

package/dist/cjs/communication/dry-run-scenario.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Ensaio da régua da SC sobre uma carteira SINTÉTICA.
+ *
+ * Executa o motor real — mesmas portas, mesma ordem, mesmas recusas — sobre uma
+ * carteira montada para cobrir cada desfecho do relatório. Não é substituto do
+ * ensaio contra a carteira do escritório: aquele exige acesso ao banco de
+ * produção e autorização humana, e é o Bloco 9.
+ *
+ * O que ele prova, e que o ensaio real não provaria melhor: que cada contador do
+ * relatório corresponde a uma decisão distinta do motor, e que nenhuma delas
+ * alcança um adapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDryRunScenario = runDryRunScenario;
+const clearance_js_1 = require("./clearance.js");
+const index_js_1 = require("./index.js");
+/**
+ * Canal que nunca envia e registra que foi chamado.
+ *
+ * Se algum destes acumular chamadas durante um ensaio, o ensaio está enviando —
+ * e é melhor descobrir por um contador do que pela fatura.
+ */
+function inertChannel(key, calls) {
+    return {
+        key,
+        providerName: 'inert',
+        // Um canal inerte não fala com provider nenhum, então não há garantia
+        // externa que ele possa declarar. Ver `capabilities.ts`.
+        capabilities: index_js_1.NO_PROVIDER_GUARANTEES,
+        isConfigured: () => true,
+        async send() {
+            calls.count += 1;
+            return { kind: 'unavailable', code: 'inert', detail: 'canal inerte de ensaio' };
+        },
+    };
+}
+async function runDryRunScenario(scenario) {
+    const calls = { count: 0 };
+    const channels = Object.fromEntries(scenario.order.map((key) => [key, inertChannel(key, calls)]));
+    const accounts = {
+        async find(ctx, channel) {
+            return (scenario.accounts.find((a) => a.channel === channel &&
+                a.tenantId === ctx.tenantId &&
+                a.product === ctx.product &&
+                a.brand === ctx.brand) ?? null);
+        },
+    };
+    const templates = {
+        async candidates(ctx, channel, eventType, locale) {
+            return scenario.templates.filter((t) => t.channel === channel &&
+                t.eventType === eventType &&
+                t.locale === locale &&
+                t.product === ctx.product &&
+                (t.tenantId === null || t.tenantId === ctx.tenantId) &&
+                (t.brand === null || t.brand === ctx.brand));
+        },
+    };
+    const byId = new Map(scenario.clients.map((c) => [c.id, c]));
+    // Chaves que a trilha já teria. Calculadas com a MESMA função do motor, e não
+    // simuladas depois sobre o resultado: um ensaio que fabrica o desfecho de
+    // "já enviado" testa o próprio cenário, não o motor.
+    const alreadySentKeys = new Set();
+    for (const client of scenario.clients) {
+        if (!client.alreadySent)
+            continue;
+        for (const channel of scenario.order) {
+            for (const tpl of scenario.templates.filter((t) => t.channel === channel && t.eventType === scenario.eventType)) {
+                alreadySentKeys.add((0, index_js_1.buildIdempotencyKey)({
+                    ctx: scenario.ctx,
+                    channel,
+                    eventType: scenario.eventType,
+                    subjectRef: `receivable-${client.id}`,
+                    templateVersion: tpl.version,
+                }));
+            }
+        }
+    }
+    const consent = {
+        async find(recipientRef, channel) {
+            return byId.get(recipientRef)?.consent.find((r) => r.channel === channel) ?? null;
+        },
+    };
+    const results = [];
+    for (const client of scenario.clients) {
+        results.push(await (0, index_js_1.dispatch)({
+            ctx: scenario.ctx,
+            eventType: scenario.eventType,
+            subjectRef: `receivable-${client.id}`,
+            recipientRef: client.id,
+            variables: {
+                clientName: client.name,
+                amount: 'R$ 1.200,00',
+                dueDate: '10/09/2026',
+            },
+            policy: { order: [...scenario.order] },
+        }, {
+            channels,
+            accounts,
+            templates,
+            consent,
+            // Ensaio não envia nada: a liberação do destinatário não tem objeto
+            // aqui, e exigi-la esconderia os pulos que o ensaio existe para
+            // mostrar.
+            clearance: clearance_js_1.CLEARANCE_NOT_REQUIRED,
+            // O telefone do cadastro é entregue CRU, sem limpeza prévia: é o motor
+            // que precisa recusar o que não serve, e um ensaio que normaliza antes
+            // esconderia exatamente o defeito que ele deveria encontrar.
+            resolveRecipient: async (ref, channel) => {
+                const c = byId.get(ref);
+                if (!c)
+                    return null;
+                return channel === 'email' ? c.email : c.phone;
+            },
+            buildContent: (channel, tpl, ordered) => {
+                if (channel === 'email') {
+                    return { kind: 'email', subject: tpl.subject ?? '', html: '', text: '' };
+                }
+                if (channel === 'whatsapp') {
+                    if (!tpl.providerTemplateName)
+                        return null;
+                    return {
+                        kind: 'whatsapp_template',
+                        templateName: tpl.providerTemplateName,
+                        language: tpl.locale,
+                        variables: ordered,
+                    };
+                }
+                return { kind: 'text', body: ordered.join(' ') };
+            },
+            /*
+             * Reserva do ensaio: LÊ, nunca toma.
+             *
+             * `claim` e `settle` lançam de propósito. Um dry-run que chegasse a
+             * reservar seria a execução real com o envio removido — e calaria a
+             * etapa de verdade —, então em vez de um no-op silencioso o cenário
+             * falha alto se o motor tentar. É o teste de mutação embutido no
+             * próprio ensaio: mover a porta de dry-run para depois do claim
+             * quebra este arquivo.
+             */
+            claims: {
+                async claim() {
+                    throw new Error('dry-run não reserva chave');
+                },
+                async settle() {
+                    throw new Error('dry-run não assenta reserva');
+                },
+                async markProviderAttempt() {
+                    // Marcar tentativa de provider num ensaio significaria que o
+                    // ensaio está prestes a falar com o provider. Lança pela mesma
+                    // razão que `claim`: é o oráculo de mutação embutido.
+                    throw new Error('dry-run não marca tentativa de provider');
+                },
+                async resolveUnknownOutcome() {
+                    throw new Error('dry-run não resolve desfecho desconhecido');
+                },
+                async peek(key) {
+                    return alreadySentKeys.has(key) ? 'sent' : 'none';
+                },
+            },
+            audit: (0, index_js_1.createNullAuditSink)(),
+        }, { dryRun: true }));
+    }
+    return { results, adapterCalls: calls.count };
+}
+//# sourceMappingURL=dry-run-scenario.js.map