@baruk/core 0.3.1 → 0.4.2

package/dist/communication/channel.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Contrato canônico de canal do ecossistema — e-mail, WhatsApp, SMS e
+ * notificação interna sob a mesma interface.
+ *
+ * O ponto de desenho está no CONTEÚDO, não na interface. A abstração de canal
+ * que já existia na cobrança da SC (`collection/channel.ts`) carregava
+ * `subject` + `html` obrigatórios: um payload de e-mail com nome genérico. Um
+ * adapter de WhatsApp receberia HTML renderizado e teria de desmontá-lo de
+ * volta em texto, e um de SMS idem — o canal vazando para dentro do domínio
+ * pela porta do payload.
+ *
+ * Aqui o conteúdo é uma união discriminada, resolvida DEPOIS que o canal foi
+ * escolhido. Cada canal recebe o que sabe entregar, e o compilador recusa o
+ * resto.
+ */
+import type { ChannelCapabilities } from './capabilities.js';
+import type { CommunicationContext } from './context.js';
+export type ChannelKey = 'email' | 'whatsapp' | 'sms' | 'notification';
+export declare const CHANNEL_KEYS: readonly ChannelKey[];
+/**
+ * Conteúdo por canal.
+ *
+ * `whatsapp_template` não é concessão à Meta — é o formato que QUALQUER
+ * provedor de WhatsApp Business exige fora da janela de 24h de conversa
+ * iniciada pelo cliente (Meta Cloud, Twilio, Zenvia, todos). Modelar isso como
+ * "texto livre" produziria código que passa em mock e é recusado em produção
+ * por toda a categoria de provider, não por um deles.
+ */
+export type MessageContent = {
+    kind: 'email';
+    subject: string;
+    html: string;
+    text: string;
+}
+/** SMS e notificação interna: texto puro, sem formatação, sem anexo. */
+ | {
+    kind: 'text';
+    body: string;
+}
+/**
+ * WhatsApp fora da janela de sessão. `variables` é POSICIONAL por imposição
+ * do canal: o template aprovado declara `{{1}}`, `{{2}}` — os nomes vivem no
+ * produto, e a ordem é o contrato.
+ */
+ | {
+    kind: 'whatsapp_template';
+    templateName: string;
+    language: string;
+    variables: string[];
+};
+/** Quais conteúdos cada canal aceita. Consultado antes do envio, não dentro do adapter. */
+export declare const CHANNEL_ACCEPTS: Record<ChannelKey, readonly MessageContent['kind'][]>;
+export declare function channelAccepts(channel: ChannelKey, content: MessageContent): boolean;
+export interface OutboundMessage {
+    ctx: CommunicationContext;
+    channel: ChannelKey;
+    /**
+     * Destinatário já normalizado para o canal: E.164 em WhatsApp/SMS, endereço
+     * em e-mail, id de usuário em notificação. Normalizar é responsabilidade do
+     * motor (`contacts/phone.ts`), nunca do adapter — dois adapters normalizando
+     * por conta própria é como o mesmo cliente recebe SMS e não recebe WhatsApp.
+     */
+    to: string;
+    content: MessageContent;
+    /** Composta pelo motor a partir do contexto. Ver `idempotency.ts`. */
+    idempotencyKey: string;
+    /** Rótulo do evento de negócio, para trilha e custo. Nunca PII. */
+    eventType: string;
+}
+/**
+ * Desfechos de entrega.
+ *
+ * Cinco, e não dois, porque cada um leva a uma decisão diferente do motor —
+ * colapsá-los em "deu certo / deu errado" faz o retry insistir no que nunca vai
+ * funcionar e desistir do que era só instabilidade.
+ *
+ *   sent        → o provider aceitou. NÃO é "chegou": ver `status.ts`.
+ *   temporary   → infraestrutura; vale tentar de novo
+ *   permanent   → destinatário/dado/template inválido; retry é desperdício
+ *   opted_out   → o destinatário recusou o canal. Não é falha e NUNCA é retry.
+ *   unavailable → o canal não existe neste contexto; não conta como tentativa
+ */
+export type DeliveryOutcomeKind = 'sent' | 'temporary' | 'permanent' | 'opted_out' | 'unavailable';
+export interface DeliveryOutcome {
+    kind: DeliveryOutcomeKind;
+    /** Identificador da mensagem no provider. Nunca uma credencial. */
+    providerRef?: string;
+    /** Rótulo curto e estável para métrica. snake_case. Nunca PII, nunca segredo. */
+    code?: string;
+    /** Detalhe legível. Nunca PII, nunca segredo. */
+    detail?: string;
+}
+export interface CommunicationChannel {
+    key: ChannelKey;
+    /**
+     * Nome do provider por trás, para a trilha ("meta_cloud", "resend"). É
+     * metadado de operação; o consumidor não ramifica por ele — se ramificasse,
+     * trocar de provider viraria mudança de regra de negócio.
+     */
+    readonly providerName: string;
+    /**
+     * O que o provider por trás garante. **Obrigatório**, e sem `?`.
+     *
+     * A ausência de opcional é a decisão: enquanto a declaração pudesse faltar, o
+     * motor teria de assumir alguma coisa para o adapter calado — e qualquer
+     * suposição sobre garantia externa é uma suposição sobre se o cliente recebe a
+     * mesma mensagem duas vezes. Agora o compilador recusa o adapter que não
+     * declara. Ver `capabilities.ts`.
+     */
+    readonly capabilities: ChannelCapabilities;
+    /** Falso quando ESTE contexto não tem o canal configurado. */
+    isConfigured(ctx: CommunicationContext): boolean | Promise<boolean>;
+    send(message: OutboundMessage): Promise<DeliveryOutcome>;
+}
+/**
+ * Canal indisponível.
+ *
+ * Deliberadamente NÃO simula entrega. Um adapter que responde `sent` sem enviar
+ * transforma a trilha em ficção: o escritório vê "cobrado" e o cliente nunca
+ * recebeu nada. Herdado da abstração da SC, que já acertou isso.
+ */
+export declare function unavailableChannel(key: ChannelKey, reason: string): CommunicationChannel;
+export type ChannelRegistry = Partial<Record<ChannelKey, CommunicationChannel>>;
+export declare function resolveChannel(registry: ChannelRegistry, key: ChannelKey): CommunicationChannel;
+//# sourceMappingURL=channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/communication/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,KAAK,GAAG,cAAc,CAAC;AAEvE,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAAiD,CAAC;AAEhG;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChE,wEAAwE;GACtE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAChC;;;;GAIG;GACD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE/F,2FAA2F;AAC3F,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,cAAc,CAAC,MAAM,CAAC,EAAE,CAKjF,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAEpF;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,oBAAoB,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,cAAc,CAAC;IACxB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;AAEnG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,UAAU,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,8DAA8D;IAC9D,YAAY,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAQxF;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAEhF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,oBAAoB,CAE/F"}

package/dist/communication/channel.js

@@ -0,0 +1,47 @@
+/**
+ * Contrato canônico de canal do ecossistema — e-mail, WhatsApp, SMS e
+ * notificação interna sob a mesma interface.
+ *
+ * O ponto de desenho está no CONTEÚDO, não na interface. A abstração de canal
+ * que já existia na cobrança da SC (`collection/channel.ts`) carregava
+ * `subject` + `html` obrigatórios: um payload de e-mail com nome genérico. Um
+ * adapter de WhatsApp receberia HTML renderizado e teria de desmontá-lo de
+ * volta em texto, e um de SMS idem — o canal vazando para dentro do domínio
+ * pela porta do payload.
+ *
+ * Aqui o conteúdo é uma união discriminada, resolvida DEPOIS que o canal foi
+ * escolhido. Cada canal recebe o que sabe entregar, e o compilador recusa o
+ * resto.
+ */
+import { NO_PROVIDER_GUARANTEES } from './capabilities.js';
+export const CHANNEL_KEYS = ['email', 'whatsapp', 'sms', 'notification'];
+/** Quais conteúdos cada canal aceita. Consultado antes do envio, não dentro do adapter. */
+export const CHANNEL_ACCEPTS = {
+    email: ['email'],
+    whatsapp: ['whatsapp_template', 'text'],
+    sms: ['text'],
+    notification: ['text'],
+};
+export function channelAccepts(channel, content) {
+    return CHANNEL_ACCEPTS[channel].includes(content.kind);
+}
+/**
+ * Canal indisponível.
+ *
+ * Deliberadamente NÃO simula entrega. Um adapter que responde `sent` sem enviar
+ * transforma a trilha em ficção: o escritório vê "cobrado" e o cliente nunca
+ * recebeu nada. Herdado da abstração da SC, que já acertou isso.
+ */
+export function unavailableChannel(key, reason) {
+    return {
+        key,
+        providerName: 'none',
+        capabilities: NO_PROVIDER_GUARANTEES,
+        isConfigured: () => false,
+        send: async () => ({ kind: 'unavailable', code: 'channel_not_configured', detail: reason }),
+    };
+}
+export function resolveChannel(registry, key) {
+    return registry[key] ?? unavailableChannel(key, `canal ${key} não registrado`);
+}
+//# sourceMappingURL=channel.js.map

package/dist/communication/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/communication/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAK3D,MAAM,CAAC,MAAM,YAAY,GAA0B,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;AAsBhG,2FAA2F;AAC3F,MAAM,CAAC,MAAM,eAAe,GAA0D;IACpF,KAAK,EAAE,CAAC,OAAO,CAAC;IAChB,QAAQ,EAAE,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,OAAmB,EAAE,OAAuB;IACzE,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzD,CAAC;AAmED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAe,EAAE,MAAc;IAChE,OAAO;QACL,GAAG;QACH,YAAY,EAAE,MAAM;QACpB,YAAY,EAAE,sBAAsB;QACpC,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK;QACzB,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;KAC5F,CAAC;AACJ,CAAC;AAID,MAAM,UAAU,cAAc,CAAC,QAAyB,EAAE,GAAe;IACvE,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,iBAAiB,CAAC,CAAC;AACjF,CAAC"}

package/dist/communication/claim.d.ts

@@ -0,0 +1,368 @@
+/**
+ * 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.
+ */
+import type { ChannelKey } from './channel.js';
+import type { CommunicationAuditSink, CommunicationEventKind } from './audit.js';
+import type { CommunicationContext } from './context.js';
+import type { SkipReason } from './policy.js';
+import type { DeliveryStatus } from './status.js';
+/** O que se quer reservar. A chave já vem composta pelo motor (`idempotency.ts`). */
+export interface DispatchClaimRequest {
+    ctx: CommunicationContext;
+    channel: ChannelKey;
+    eventType: string;
+    subjectRef: string;
+    idempotencyKey: string;
+    /**
+     * Referência LÓGICA do destinatário. Nunca telefone, nunca e-mail.
+     *
+     * Vem no pedido de reserva — e não só na trilha do motor — porque a trilha do
+     * ciclo de vida do disparo passou a ser gravada AQUI, na mesma fronteira
+     * transacional da reserva. Ver a nota sobre durabilidade abaixo.
+     */
+    recipientRef: string;
+}
+/**
+ * A reserva concedida. Devolvida a `settle` para assentar o desfecho.
+ *
+ * `attempt` é o número da tentativa desta chave, contando a atual. Vale mais que
+ * um booleano: `attempt > 1` numa reserva concedida por EXPIRAÇÃO significa que
+ * um processo anterior morreu segurando o direito de enviar.
+ */
+export interface DispatchClaimHandle {
+    /** Identidade da LINHA de reserva. Estável entre tentativas da mesma chave. */
+    claimId: string;
+    /**
+     * Identidade desta GERAÇÃO da reserva — o fencing token.
+     *
+     * Muda a cada concessão, inclusive quando a reserva é retomada de um titular
+     * vencido. É o que permite a `settle` recusar o zumbi: `claimId` sozinho não
+     * serve, porque a linha é a mesma para o titular vencido e para o atual, e um
+     * `WHERE` por `claimId` deixaria o processo que ressuscita assentar por cima de
+     * quem está enviando neste instante.
+     *
+     * Prazo NÃO é fencing. Um titular vencido que acorda continua com um relógio
+     * plausível na mão; o que o desqualifica é não ter a geração corrente.
+     */
+    claimToken: string;
+    idempotencyKey: string;
+    attempt: number;
+    /**
+     * A reserva foi tomada de um titular anterior cujo prazo venceu.
+     *
+     * Sozinho, NÃO decide nada — diz apenas que houve um titular que não assentou.
+     * A pergunta que decide é a próxima.
+     */
+    recoveredFromExpiredClaim: boolean;
+    /**
+     * O titular anterior chegou a chamar o provider.
+     *
+     * `true` significa desfecho **UNKNOWN**, não "não enviado": a mensagem pode ter
+     * saído. É a condição que o motor consulta antes de decidir se reenvia, e é o
+     * que separa recuperação segura de recuperação cega.
+     */
+    previousAttemptReachedProvider: boolean;
+    /**
+     * Há quanto tempo (ms) foi a PRIMEIRA chamada externa desta chave, se houve.
+     *
+     * A janela de idempotência do provider conta a partir dela, não da tentativa
+     * atual: uma chave que o provider já esqueceu não protege mais nada.
+     *
+     * Idade, e não instante, porque quem mede é quem guarda: o store SQL usa o
+     * relógio do banco, o de memória usa o dele. Devolver o instante obrigaria o
+     * motor a compará-lo com o relógio do PROCESSO, e dois relógios que não
+     * concordam decidem errado sobre reenviar ou não.
+     */
+    providerFirstAttemptAgeMs: number | null;
+}
+/**
+ * Por que a reserva não foi concedida.
+ *
+ * Cada motivo leva a uma leitura operacional diferente, e por isso nenhum deles
+ * é "não deu": `already_sent` é o sistema funcionando; `in_flight` é
+ * concorrência sendo absorvida; `permanently_failed` e `unknown_outcome` são
+ * coisas que precisam de humano — e por motivos opostos.
+ */
+export type ClaimRefusal = 'already_sent' | 'in_flight' | 'permanently_failed'
+/**
+ * A chave está parada em desfecho DESCONHECIDO: alguém chamou o provider e
+ * ninguém sabe o que aconteceu.
+ *
+ * Não é falha (pode ter dado certo) e não é sucesso (pode não ter saído). Fica
+ * travada de propósito: destravar sozinha seria escolher, no escuro, entre
+ * calar um aviso e mandar dois. Sai daqui por `resolveUnknownOutcome`.
+ */
+ | 'unknown_outcome';
+export type ClaimResult = {
+    granted: true;
+    claim: DispatchClaimHandle;
+} | {
+    granted: false;
+    reason: ClaimRefusal;
+    detail?: string;
+};
+/**
+ * Desfecho a assentar.
+ *
+ * `released` é o caso que não existia no desenho antigo e que a reserva torna
+ * obrigatório: reservei e NÃO enviei (dry-run, conteúdo recusado na borda). Sem
+ * ele a chave ficaria presa até o prazo vencer, e o ensaio calaria a etapa real.
+ *
+ * `unknown` é o da H2: reservei, descobri que o titular anterior pode ter enviado
+ * e NÃO tenho como garantir que um reenvio não duplica. Assentar como falha
+ * devolveria a chave e a próxima rodada duplicaria; assentar como enviada
+ * afirmaria uma entrega que ninguém viu.
+ */
+export type ClaimSettlement = {
+    kind: 'sent';
+    providerRef?: string;
+} | {
+    kind: 'failed';
+    permanent: boolean;
+    code?: string;
+    detail?: string;
+} | {
+    kind: 'released';
+    reason: string;
+} | {
+    kind: 'unknown';
+    code?: string;
+    detail?: string;
+};
+/**
+ * O evento de trilha que acompanha a transição.
+ *
+ * Vai JUNTO com o `settle`, na mesma gravação, e é isso que o torna durável.
+ * Ver a nota sobre fronteira transacional abaixo.
+ */
+export interface DispatchLifecycleEvent {
+    kind: CommunicationEventKind;
+    providerRef?: string | null;
+    skipReason?: SkipReason | null;
+    status?: DeliveryStatus | null;
+    code?: string | null;
+    detail?: string | null;
+}
+/** Como um desfecho desconhecido foi resolvido por quem investigou. */
+export type UnknownResolution = 'sent' | 'not_sent';
+/**
+ * Veredicto do FENCING PRÉ-PROVIDER: quem chama ainda é o titular do direito de
+ * enviar, agora, no armazenamento?
+ *
+ * ## Por que isto existe
+ *
+ * `markProviderAttempt` devolvia `void`. A trava por geração estava no `WHERE` do
+ * `UPDATE` — e funcionava: a linha do zumbi não era atualizada. Mas o motor não
+ * tinha como saber disso. Gravava (ou não gravava) a marca e seguia direto para
+ * `adapter.send()`. O resultado é o que a terceira certificação encontrou:
+ *
+ *     A perde a reserva por prazo  →  B a retoma e envia
+ *     A acorda, "marca" a tentativa (nenhuma linha muda)  →  A envia também
+ *
+ * Duas chamadas ao provider para a mesma intenção, com a trava de fencing
+ * presente, correta e **muda**. Uma trava cujo resultado o chamador ignora não é
+ * trava: é um `UPDATE` que às vezes não faz nada.
+ *
+ * Por isso o retorno é uma união DISCRIMINADA, e não um booleano. `held` e `lost`
+ * já bastariam para abortar, mas colapsariam duas coisas que quem opera precisa
+ * distinguir: "outro worker está com a reserva" e "esta chave já foi assentada".
+ * A primeira é concorrência normal; a segunda é o motor sendo chamado sobre um
+ * disparo que acabou.
+ *
+ * ## O que NÃO está aqui, e por quê
+ *
+ * Não há membro `unknown`. Falha de GRAVAÇÃO da marca (banco fora, timeout) não
+ * é desfecho incerto: nada foi enviado ainda, porque a marca vem antes da
+ * chamada externa. Esse caso LANÇA — e é deliberado. Ver a nota em `engine.ts`
+ * sobre o `markProviderAttempt` ficar fora do `try` do adapter: deixar a exceção
+ * subir faz a reserva simplesmente expirar, e a retomada seguinte é segura
+ * justamente porque não existe marca nenhuma. Devolver `unknown` aqui travaria a
+ * chave por uma falha de banco num envio que nem começou.
+ */
+export type ProviderAttemptFence = 
+/** A geração corrente é a de quem chamou. Autorizado a chamar o provider. */
+{
+    authority: 'held';
+}
+/**
+ * A reserva mudou de mãos (prazo vencido e retomada por outro), ou a linha não
+ * existe mais. **Quem recebe isto não chama o provider.**
+ */
+ | {
+    authority: 'lost';
+    detail: string;
+}
+/**
+ * A chave já está assentada — `sent`, `failed_permanent`, `unknown_outcome`.
+ *
+ * Recorte próprio de `lost` porque a ação de quem investiga é outra: em `lost`
+ * há um titular novo trabalhando agora; aqui não há titular nenhum, e o disparo
+ * terminou.
+ */
+ | {
+    authority: 'already_final';
+    state: DispatchKeyState;
+    detail: string;
+};
+/** Estado de uma chave, para LEITURA pura. Nunca reserva nada. */
+export type DispatchKeyState = 'none' | 'in_flight' | 'sent' | 'failed_retryable' | 'failed_permanent' | 'unknown_outcome';
+/**
+ * Porta de reserva. Implementada pelo produto, sobre o armazenamento dele.
+ *
+ * O motor não sabe se é Postgres, Redis ou outra coisa; sabe que `claim` é
+ * atômico em relação a outros `claim` da mesma chave — **inclusive entre
+ * processos diferentes**. Uma implementação que só coordene dentro de um
+ * processo satisfaz a interface e não satisfaz o requisito: ver a nota em
+ * `createInMemoryDispatchClaimStore`.
+ *
+ * ## A trilha do ciclo de vida mora AQUI
+ *
+ * `dispatch_claimed`, `dispatch_sent`, `dispatch_failed` são gravados pelo store,
+ * na MESMA fronteira transacional da reserva — não pelo `audit` do motor.
+ *
+ * A razão é um defeito concreto que a certificação achou. O `audit` do motor
+ * escreve na transação de NEGÓCIO de quem chamou (a régua de cobrança roda o
+ * ciclo inteiro numa transação longa). A reserva, ao contrário, commita em
+ * transação própria e curta, porque precisa ficar visível a outros workers antes
+ * do fim do ciclo. Se a transação longa fizesse rollback DEPOIS de a mensagem
+ * sair, o resultado era:
+ *
+ *     communication_dispatch.status = 'sent'     (sobreviveu — a mensagem saiu)
+ *     communication_event.dispatch_sent          (sumiu — a narrativa foi desfeita)
+ *
+ * Um disparo enviado sem nenhuma linha explicando que foi enviado. Juntando a
+ * gravação do evento à gravação da reserva, as duas caem ou sobrevivem juntas —
+ * uma escrita, não duas. Não é outbox nem dual-write com compensação: é a mesma
+ * transação, que é o padrão mais simples que satisfaz a exigência.
+ *
+ * O que continua no `audit` do motor: `intent_created` e os pulos ANTERIORES à
+ * reserva. Esses descrevem decisões sem efeito externo nenhum — se a transação de
+ * negócio cair, nada saiu, e a narrativa não deve mesmo sobreviver.
+ */
+export interface DispatchClaimStore {
+    /** Reserva e grava `dispatch_claimed` na mesma fronteira. */
+    claim(req: DispatchClaimRequest): Promise<ClaimResult>;
+    /**
+     * Marca, DURAVELMENTE, que a chamada externa vai acontecer agora — **e devolve
+     * se quem pediu ainda tem autoridade para fazê-la.**
+     *
+     * Chamada imediatamente antes de `adapter.send`, e não junto com o `claim`: se
+     * a marca viesse no `claim`, todo processo que morresse entre reservar e
+     * enviar travaria a chave num "desconhecido" que não existe.
+     *
+     * É a ÚLTIMA fronteira persistente antes do efeito externo, e por isso as duas
+     * coisas — marcar e verificar autoridade — são a MESMA operação, atômica. Um
+     * `peek` seguido de `send` reabriria a janela TOCTOU que a reserva existe para
+     * fechar: entre ler o estado e chamar o provider, a reserva pode trocar de
+     * mãos. Aqui não pode: ou o `UPDATE` casa a geração corrente e a marca fica
+     * gravada, ou ele não casa nada e o veredicto é `lost`.
+     *
+     * Implementações NÃO devem devolver `held` quando nenhuma linha foi atualizada.
+     * É esse "sucesso genérico" que a terceira certificação encontrou — ver
+     * `ProviderAttemptFence`.
+     */
+    markProviderAttempt(claim: DispatchClaimHandle): Promise<ProviderAttemptFence>;
+    /** Assenta o desfecho e grava o evento correspondente na mesma gravação. */
+    settle(claim: DispatchClaimHandle, outcome: ClaimSettlement, event: DispatchLifecycleEvent): Promise<void>;
+    /**
+     * Estado atual da chave, sem reservar.
+     *
+     * Existe para o dry-run: o ensaio precisa relatar "isto já saiu" com a mesma
+     * verdade da execução, e não pode fazê-lo tomando uma reserva — um ensaio que
+     * escreve não é ensaio.
+     */
+    peek(idempotencyKey: string): Promise<DispatchKeyState>;
+    /**
+     * Saída do estado desconhecido, por decisão de quem investigou.
+     *
+     * `sent` encerra a chave (a mensagem saiu; não reenviar). `not_sent` a devolve
+     * para retentável (não saiu; a próxima rodada pode enviar). É deliberadamente
+     * uma operação EXPLÍCITA: nenhum caminho automático adivinha o que aconteceu no
+     * provider, porque adivinhar aqui é escolher entre calar um aviso e cobrar duas
+     * vezes.
+     */
+    resolveUnknownOutcome(idempotencyKey: string, resolution: UnknownResolution, detail?: string): Promise<void>;
+}
+/** Prazo da reserva. Ver `createInMemoryDispatchClaimStore` para o raciocínio. */
+export declare const DEFAULT_CLAIM_TTL_MS: number;
+export interface InMemoryClaimStoreOptions {
+    ttlMs?: number;
+    now?: () => number;
+    /**
+     * Destino da trilha de ciclo de vida.
+     *
+     * Existe para que a implementação em memória tenha a MESMA fronteira que a
+     * SQL: lá o evento cai na transação da reserva, aqui ele cai no sink que o
+     * store recebeu — em nenhum dos dois casos ele depende da transação de negócio
+     * de quem chamou. Um store de teste que gravasse a trilha por outro caminho
+     * mediria uma propriedade diferente da que produção tem.
+     */
+    audit?: CommunicationAuditSink;
+}
+/**
+ * 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).
+ */
+export declare function createInMemoryDispatchClaimStore(options?: InMemoryClaimStoreOptions): DispatchClaimStore;
+//# sourceMappingURL=claim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../../src/communication/claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,oBAAoB,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;OAWG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,yBAAyB,EAAE,OAAO,CAAC;IACnC;;;;;;OAMG;IACH,8BAA8B,EAAE,OAAO,CAAC;IACxC;;;;;;;;;;OAUG;IACH,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB,cAAc,GACd,WAAW,GACX,oBAAoB;AACtB;;;;;;;GAOG;GACD,iBAAiB,CAAC;AAEtB,MAAM,MAAM,WAAW,GACnB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC7C;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,oBAAoB;AAC9B,6EAA6E;AAC3E;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE;AACvB;;;GAGG;GACD;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACvC;;;;;;GAMG;GACD;IAAE,SAAS,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,kEAAkE;AAClE,MAAM,MAAM,gBAAgB,GAC1B,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAE9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,KAAK,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACvD;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC/E,4EAA4E;IAC5E,MAAM,CACJ,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;OAMG;IACH,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACxD;;;;;;;;OAQG;IACH,qBAAqB,CACnB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,iBAAiB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAAiB,CAAC;AAanD,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAqKpB"}