@baruk/core 0.3.0 → 0.4.2

package/dist/communication/dry-run-scenario.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+import { type ChannelAccount, type ChannelKey, type CommunicationContext, type ConsentRecord, type DispatchResult, type TemplateRecord } from './index.js';
+export interface DryRunClient {
+    id: string;
+    name: string;
+    /** Como está no cadastro — inclusive torto, que é o ponto do ensaio. */
+    phone: string | null;
+    email: string | null;
+    consent: ConsentRecord[];
+    alreadySent?: boolean;
+}
+export interface DryRunScenario {
+    ctx: CommunicationContext;
+    clients: readonly DryRunClient[];
+    accounts: readonly ChannelAccount[];
+    templates: readonly TemplateRecord[];
+    order: readonly ChannelKey[];
+    eventType: string;
+}
+export interface DryRunRun {
+    results: DispatchResult[];
+    /** Deve ser 0. Qualquer outro valor significa que o ensaio tocou um adapter. */
+    adapterCalls: number;
+}
+export declare function runDryRunScenario(scenario: DryRunScenario): Promise<DryRunRun>;
+//# sourceMappingURL=dry-run-scenario.d.ts.map

package/dist/communication/dry-run-scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run-scenario.d.ts","sourceRoot":"","sources":["../../src/communication/dry-run-scenario.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,cAAc,EAEnB,KAAK,UAAU,EAEf,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAElB,KAAK,cAAc,EAEnB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,oBAAoB,CAAC;IAC1B,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IACpC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAuBD,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAkJpF"}

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

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+import { buildIdempotencyKey, createNullAuditSink, dispatch, NO_PROVIDER_GUARANTEES, } from './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: NO_PROVIDER_GUARANTEES,
+        isConfigured: () => true,
+        async send() {
+            calls.count += 1;
+            return { kind: 'unavailable', code: 'inert', detail: 'canal inerte de ensaio' };
+        },
+    };
+}
+export 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(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 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,
+            // 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: createNullAuditSink(),
+        }, { dryRun: true }));
+    }
+    return { results, adapterCalls: calls.count };
+}
+//# sourceMappingURL=dry-run-scenario.js.map

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

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

package/dist/communication/dry-run.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Agregação de um ensaio.
+ *
+ * O dry-run só é útil se contar as recusas com a mesma granularidade das
+ * decisões: "12 não sairiam" não diz se o escritório precisa preencher
+ * cadastros, colher autorizações ou configurar um canal — e cada uma dessas
+ * respostas leva a um trabalho diferente.
+ */
+import type { ChannelKey } from './channel.js';
+import type { DispatchResult } from './engine.js';
+export interface DryRunReport {
+    /** Quantas mensagens sairiam por canal. */
+    wouldSend: Record<ChannelKey, number>;
+    skipNoPhone: number;
+    skipInvalidPhone: number;
+    skipOptOut: number;
+    skipConsentUnknown: number;
+    skipAlreadySent: number;
+    skipChannelNotReady: number;
+    skipNoTemplate: number;
+    /** Nem enviaria nem tem motivo classificado — sempre deve ser zero. */
+    unclassified: number;
+    examined: number;
+}
+export declare function emptyDryRunReport(): DryRunReport;
+/**
+ * Conta UM desfecho por intenção, não um por canal tentado.
+ *
+ * A distinção importa: uma intenção que pula WhatsApp por falta de telefone e
+ * sai por e-mail é UMA mensagem enviada, não "uma enviada e uma pulada". Somar
+ * as duas infla o relatório e faz o escritório procurar problema onde a régua
+ * se resolveu sozinha.
+ *
+ * O motivo registrado é o do PRIMEIRO canal recusado — o preferido, que é o que
+ * o escritório precisa consertar para a mensagem sair pela via que ele escolheu.
+ */
+export declare function summarizeDryRun(results: readonly DispatchResult[]): DryRunReport;
+/** Linhas do relatório, no formato que o Bloco 8 exige. Sem PII, sem segredo. */
+export declare function formatDryRunReport(report: DryRunReport): string[];
+//# sourceMappingURL=dry-run.d.ts.map

package/dist/communication/dry-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../../src/communication/dry-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAahD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,YAAY,CA4ChF;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAejE"}

package/dist/communication/dry-run.js

@@ -0,0 +1,92 @@
+/**
+ * Agregação de um ensaio.
+ *
+ * O dry-run só é útil se contar as recusas com a mesma granularidade das
+ * decisões: "12 não sairiam" não diz se o escritório precisa preencher
+ * cadastros, colher autorizações ou configurar um canal — e cada uma dessas
+ * respostas leva a um trabalho diferente.
+ */
+export function emptyDryRunReport() {
+    return {
+        wouldSend: { email: 0, whatsapp: 0, sms: 0, notification: 0 },
+        skipNoPhone: 0,
+        skipInvalidPhone: 0,
+        skipOptOut: 0,
+        skipConsentUnknown: 0,
+        skipAlreadySent: 0,
+        skipChannelNotReady: 0,
+        skipNoTemplate: 0,
+        unclassified: 0,
+        examined: 0,
+    };
+}
+/**
+ * Conta UM desfecho por intenção, não um por canal tentado.
+ *
+ * A distinção importa: uma intenção que pula WhatsApp por falta de telefone e
+ * sai por e-mail é UMA mensagem enviada, não "uma enviada e uma pulada". Somar
+ * as duas infla o relatório e faz o escritório procurar problema onde a régua
+ * se resolveu sozinha.
+ *
+ * O motivo registrado é o do PRIMEIRO canal recusado — o preferido, que é o que
+ * o escritório precisa consertar para a mensagem sair pela via que ele escolheu.
+ */
+export function summarizeDryRun(results) {
+    const report = emptyDryRunReport();
+    for (const result of results) {
+        report.examined += 1;
+        if (result.delivered) {
+            report.wouldSend[result.delivered] += 1;
+            continue;
+        }
+        const first = result.attempts.find((a) => a.skipped);
+        switch (first?.skipped) {
+            case 'no_recipient':
+                report.skipNoPhone += 1;
+                break;
+            case 'invalid_recipient':
+                report.skipInvalidPhone += 1;
+                break;
+            case 'opted_out':
+                report.skipOptOut += 1;
+                break;
+            case 'consent_unknown':
+                report.skipConsentUnknown += 1;
+                break;
+            case 'already_sent':
+                report.skipAlreadySent += 1;
+                break;
+            case 'channel_not_registered':
+            case 'no_identity':
+                report.skipChannelNotReady += 1;
+                break;
+            case 'no_template':
+                report.skipNoTemplate += 1;
+                break;
+            default:
+                // Inclui o contexto inválido e as falhas de adapter. Num ensaio nenhum
+                // adapter é chamado, então qualquer valor aqui é defeito de integração
+                // — e é por isso que o campo existe em vez de o caso cair em silêncio.
+                report.unclassified += 1;
+        }
+    }
+    return report;
+}
+/** Linhas do relatório, no formato que o Bloco 8 exige. Sem PII, sem segredo. */
+export function formatDryRunReport(report) {
+    return [
+        `WOULD_SEND_EMAIL=${report.wouldSend.email}`,
+        `WOULD_SEND_WHATSAPP=${report.wouldSend.whatsapp}`,
+        `WOULD_SEND_SMS=${report.wouldSend.sms}`,
+        `SKIP_NO_PHONE=${report.skipNoPhone}`,
+        `SKIP_INVALID_PHONE=${report.skipInvalidPhone}`,
+        `SKIP_OPT_OUT=${report.skipOptOut}`,
+        `SKIP_CONSENT_UNKNOWN=${report.skipConsentUnknown}`,
+        `SKIP_ALREADY_SENT=${report.skipAlreadySent}`,
+        `SKIP_CHANNEL_NOT_READY=${report.skipChannelNotReady}`,
+        `SKIP_NO_TEMPLATE=${report.skipNoTemplate}`,
+        `UNCLASSIFIED=${report.unclassified}`,
+        `EXAMINED=${report.examined}`,
+    ];
+}
+//# sourceMappingURL=dry-run.js.map

package/dist/communication/dry-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry-run.js","sourceRoot":"","sources":["../../src/communication/dry-run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE;QAC7D,WAAW,EAAE,CAAC;QACd,gBAAgB,EAAE,CAAC;QACnB,UAAU,EAAE,CAAC;QACb,kBAAkB,EAAE,CAAC;QACrB,eAAe,EAAE,CAAC;QAClB,mBAAmB,EAAE,CAAC;QACtB,cAAc,EAAE,CAAC;QACjB,YAAY,EAAE,CAAC;QACf,QAAQ,EAAE,CAAC;KACZ,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,OAAkC;IAChE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IAEnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;QAErB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACxC,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QACrD,QAAQ,KAAK,EAAE,OAAO,EAAE,CAAC;YACvB,KAAK,cAAc;gBACjB,MAAM,CAAC,WAAW,IAAI,CAAC,CAAC;gBACxB,MAAM;YACR,KAAK,mBAAmB;gBACtB,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC;gBAC7B,MAAM;YACR,KAAK,WAAW;gBACd,MAAM,CAAC,UAAU,IAAI,CAAC,CAAC;gBACvB,MAAM;YACR,KAAK,iBAAiB;gBACpB,MAAM,CAAC,kBAAkB,IAAI,CAAC,CAAC;gBAC/B,MAAM;YACR,KAAK,cAAc;gBACjB,MAAM,CAAC,eAAe,IAAI,CAAC,CAAC;gBAC5B,MAAM;YACR,KAAK,wBAAwB,CAAC;YAC9B,KAAK,aAAa;gBAChB,MAAM,CAAC,mBAAmB,IAAI,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,aAAa;gBAChB,MAAM,CAAC,cAAc,IAAI,CAAC,CAAC;gBAC3B,MAAM;YACR;gBACE,uEAAuE;gBACvE,uEAAuE;gBACvE,uEAAuE;gBACvE,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO;QACL,oBAAoB,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE;QAC5C,uBAAuB,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE;QAClD,kBAAkB,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE;QACxC,iBAAiB,MAAM,CAAC,WAAW,EAAE;QACrC,sBAAsB,MAAM,CAAC,gBAAgB,EAAE;QAC/C,gBAAgB,MAAM,CAAC,UAAU,EAAE;QACnC,wBAAwB,MAAM,CAAC,kBAAkB,EAAE;QACnD,qBAAqB,MAAM,CAAC,eAAe,EAAE;QAC7C,0BAA0B,MAAM,CAAC,mBAAmB,EAAE;QACtD,oBAAoB,MAAM,CAAC,cAAc,EAAE;QAC3C,gBAAgB,MAAM,CAAC,YAAY,EAAE;QACrC,YAAY,MAAM,CAAC,QAAQ,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/dist/communication/engine.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Motor de comunicação compartilhado.
+ *
+ *   INTENT → CONTEXT → POLICY → IDENTITY → CONSENT → RECIPIENT → TEMPLATE
+ *          → CONTENT → CLAIM → [RECOVERY?] → FENCE → ADAPTER → SETTLE
+ *
+ * O consumidor declara a INTENÇÃO de negócio ("avisar este cliente sobre o
+ * recebível X, etapa D+3, preferindo WhatsApp"). O motor decide nada sobre o
+ * negócio e tudo sobre a entrega.
+ *
+ * Cada porta abaixo pode recusar, e **toda recusa tem motivo próprio**. Um motor
+ * que devolve "não enviado" sem dizer qual porta fechou obriga o escritório a
+ * adivinhar entre "o cliente pediu para não receber" e "ninguém cadastrou o
+ * telefone" — que exigem ações opostas de quem opera.
+ *
+ * **CLAIM é a penúltima porta, e é a mais importante.** Ela fica imediatamente
+ * antes do adapter porque é o único lugar onde uma reserva serve para alguma
+ * coisa: a proteção contra envio duplo tem de acontecer antes do efeito externo,
+ * nunca depois. Ver `claim.ts`.
+ *
+ * Entre CLAIM e ADAPTER existem duas etapas que a H2 acrescentou, e nenhuma das
+ * duas é opcional:
+ *
+ *   RECOVERY  quando a reserva foi retomada de um titular que já tinha falado com
+ *             o provider, o desfecho anterior é DESCONHECIDO. O motor só reenvia
+ *             se o adapter declarar idempotência de provider que ainda cubra a
+ *             chave; sem isso, recusa e deixa a chave visível para quem opera.
+ *   FENCE     a marca durável de "vou chamar o provider agora", gravada antes da
+ *             chamada — e, na MESMA operação, a prova de que quem vai chamar
+ *             ainda é o titular da geração corrente. É ela que dá à próxima
+ *             retomada como saber a diferença entre "morreu antes de enviar" e
+ *             "morreu depois", e é ela que impede o titular vencido de alcançar
+ *             o provider. Perdeu a autoridade, não chama: sem exceção.
+ *
+ * A trilha do CICLO DE VIDA do disparo (`dispatch_claimed`, `dispatch_sent`,
+ * `dispatch_failed`) é gravada pelo STORE, junto com a reserva, e não pelo
+ * `audit` daqui. A razão está em `claim.ts`: o `audit` do motor vive na transação
+ * de negócio de quem chamou, e um rollback dela apagava a narrativa de um envio
+ * que tinha acontecido de verdade.
+ */
+import { type ChannelKey, type ChannelRegistry, type MessageContent } from './channel.js';
+import { type CommunicationAuditSink } from './audit.js';
+import type { DispatchClaimStore } from './claim.js';
+import { type CommunicationContext } from './context.js';
+import { type ConsentPolicy, type ConsentStore } from './consent.js';
+import { type ChannelAccountStore } from './identity.js';
+import { type ChannelAttempt, type ChannelPolicy } from './policy.js';
+import { type TemplateStore } from './template.js';
+/** O que o produto declara querer comunicar. */
+export interface CommunicationIntent {
+    ctx: CommunicationContext;
+    /** `billing.dunning.d3` — do vocabulário do consumidor, não do motor. */
+    eventType: string;
+    /** Referência do assunto no domínio do consumidor. Entra na idempotência. */
+    subjectRef: string;
+    /** Referência do destinatário no domínio do consumidor. NUNCA o telefone. */
+    recipientRef: string;
+    /** Valores das variáveis, por nome. O template define a ordem. */
+    variables: Record<string, string>;
+    policy?: ChannelPolicy;
+    locale?: string;
+}
+export interface DispatchDeps {
+    channels: ChannelRegistry;
+    accounts: ChannelAccountStore;
+    templates: TemplateStore;
+    consent: ConsentStore;
+    consentPolicy?: ConsentPolicy;
+    /**
+     * Reserva atômica do direito de enviar. **Obrigatória.**
+     *
+     * Não é opcional, e a ausência de `?` é a decisão de desenho: enquanto era
+     * `alreadySent?`, todo consumidor que esquecesse de passá-la ganhava um motor
+     * sem proteção nenhuma contra envio duplo — em silêncio, com os testes
+     * passando. Agora o compilador recusa o consumidor incompleto.
+     */
+    claims: DispatchClaimStore;
+    /** Trilha estruturada. Obrigatória pela mesma razão que `claims`. */
+    audit: CommunicationAuditSink;
+    /**
+     * Endereço do destinatário PARA ESTE CANAL, já normalizado, ou `null`.
+     *
+     * Do produto, porque só ele sabe onde o contato do cliente mora. A
+     * normalização canônica de telefone é do motor (`contacts/phone.ts`) e o
+     * produto deve usá-la — dois normalizadores é como o mesmo cliente recebe SMS
+     * e não recebe WhatsApp.
+     */
+    resolveRecipient: (recipientRef: string, channel: ChannelKey) => Promise<string | null>;
+    /** Monta o conteúdo para o canal escolhido. Do produto: é ele que tem o texto. */
+    buildContent: (channel: ChannelKey, template: {
+        providerTemplateName?: string;
+        body?: string;
+        subject?: string;
+        locale: string;
+    }, ordered: string[], variables: Record<string, string>) => MessageContent | null;
+}
+export interface DispatchResult {
+    /** Canal que efetivamente entregou, ou `null` quando nenhum entregou. */
+    delivered: ChannelKey | null;
+    providerRef?: string;
+    /** Tudo que foi tentado, na ordem, com o motivo de cada recusa. */
+    attempts: ChannelAttempt[];
+    /** Chave usada. Devolvida para o consumidor gravar na trilha. */
+    idempotencyKey: string;
+    /** Contexto rejeitado na borda — nenhum canal chegou a ser tentado. */
+    invalidContext?: 'tenant' | 'product' | 'brand';
+    /**
+     * Quantas vezes `adapter.send` foi chamado nesta execução.
+     *
+     * Existe para ser ASSERTADO. A prova de que a reserva funciona não é "o
+     * segundo dispatch devolveu `already_sent`" — é que o adapter foi acionado uma
+     * vez só. Contar aqui, dentro do motor, torna a afirmação verificável sem
+     * depender de o teste espionar o adapter certo.
+     *
+     * **Conta o ADAPTER, não a rede.** Um adapter que recusa antes de qualquer
+     * chamada externa — a trava `liveSend` do WhatsApp, por exemplo — soma 1 aqui
+     * e não falou com ninguém. A prova de que nada real saiu é a trava do adapter,
+     * verificada em `communication-real-send-guard.test.ts`; este contador prova
+     * outra coisa, que é a ausência de disparo duplo.
+     */
+    providerSendCalls: number;
+    /**
+     * A reserva foi tomada de um titular cujo prazo venceu — há risco real de o
+     * titular anterior ter enviado antes de morrer. Ver `claim.ts`.
+     */
+    recoveredFromExpiredClaim?: boolean;
+    /**
+     * O reenvio aconteceu sob garantia de idempotência do PROVIDER.
+     *
+     * `true` quer dizer: a tentativa anterior falou com o provider, este envio
+     * repetiu a MESMA chave, e a deduplicação é do outro lado. O adapter foi
+     * chamado; a mensagem, não necessariamente saiu duas vezes — é a distinção
+     * entre `providerSendCalls` e efeito externo, e ela precisa ser visível para
+     * quem audita.
+     */
+    providerIdempotentReplay?: boolean;
+}
+export interface DispatchOptions {
+    /**
+     * `true` percorre todas as portas e relata o que ACONTECERIA, sem chamar
+     * nenhum adapter e **sem tomar reserva nenhuma**.
+     *
+     * A decisão de desenho é onde o dry-run corta: depois de resolver identidade,
+     * consentimento, destinatário, template e conteúdo — e antes de `claim`.
+     * Cortar antes disso produziria um ensaio que aprova o que a execução real
+     * recusa, que é pior que não ensaiar
+     * (`feedback_dont_swap_the_measuring_instrument`). Cortar DEPOIS do claim
+     * seria pior ainda: o ensaio consumiria a chave e calaria a etapa de verdade.
+     */
+    dryRun?: boolean;
+}
+export declare function dispatch(intent: CommunicationIntent, deps: DispatchDeps, options?: DispatchOptions): Promise<DispatchResult>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/communication/engine.d.ts.map

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