@ultimat3/notify 29.3.2 → 30.0.0

package/src/fanout-digest.ts

@@ -4,6 +4,7 @@
 // Exactly one run opens a given window, so exactly one sleeps on it — which is what stops fifty
 // events in one hour from scheduling fifty flushes of the same digest.
 
+import type { StepOutput } from '@ultimat3/jobs';
 import { attemptDelivery } from './attempt';
 import type { NotifyChannel } from './channel';
 import type { DigestSlot } from './digest';
@@ -78,7 +79,7 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
       digest.drain(slotFor(id), endsAt),
     );
     if (batch.length === 0) continue;
-    const events = rehydrate<Params>(batch);
+    const events = rehydrate(batch, plan.parseParams);
     const newest = events[events.length - 1] ?? event;
     const sent = await step.run(`digest-send:${channel.name}:${id}`, (signal) =>
       attemptDelivery(
@@ -86,10 +87,11 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
           ledger: notifyStores().ledger,
           // The window, not the event: a digest is one delivery for many events, so its ledger
           // identity is the slot plus the window it closed. Two different windows for the same
-          // recipient are two deliveries and must not dedupe into one.
+          // recipient are two deliveries and must not dedupe into one. THIS recipient's end, never
+          // the run's maximum: two runs whose maxima coincide would share one key across windows.
           claim: {
             notifier: plan.name,
-            key: `digest:${group}:${String(opened.endsAt)}`,
+            key: `digest:${group}:${String(endsAt)}`,
             recipient: id,
             channel: channel.name,
           },
@@ -109,14 +111,16 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
 }
 
 /**
- * A step's return value round-trips through JSON, so a replayed batch arrives with `at` as an ISO
- * string that the type still calls a `Date`. Rebuilt here rather than trusted — a channel that
- * formats it would throw on `at.getTime` only on the replay path, which is the path nothing tests.
- *
- * The cast is the digest store's untyped edge: it holds `NotifyEvent<unknown>` because one store
- * serves every notifier, and what comes out of a slot is exactly what this notifier put in.
+ * A step answers the stored form, so the drained batch holds `at` and any date in `params` as ISO
+ * strings on every attempt, and a channel is promised a `Date` and `Params`: both rebuilt here,
+ * `params` through the notifier's own `input`, the parse a job's payload gets off the queue.
  */
 const rehydrate = <Params>(
-  batch: readonly NotifyEvent<unknown>[],
+  batch: StepOutput<readonly NotifyEvent<unknown>[]>,
+  parseParams: (raw: unknown) => Params,
 ): readonly NotifyEvent<Params>[] =>
-  batch.map((entry) => ({ ...entry, at: new Date(entry.at) })) as readonly NotifyEvent<Params>[];
+  batch.map((entry) => ({
+    ...entry,
+    at: new Date(entry.at),
+    params: parseParams(entry.params),
+  }));

package/src/fanout.ts

@@ -25,8 +25,8 @@ export async function runFanout<Params>(
   const { input, step, ctx, runId } = args;
   // One step for BOTH facts, because both must survive a replay: a re-resolved audience would
   // deliver to whoever subscribed during the wait, and a re-read clock would write a different
-  // `at` into the inbox on every attempt. Epoch ms rather than a `Date` — a step's return value
-  // round-trips through JSON, and a `Date` comes back a string.
+  // `at` into the inbox on every attempt. Epoch ms rather than a `Date`: a step answers the stored
+  // form, where a `Date` is a string.
   const open = await step.run('open', async () => ({
     at: ctx.now().getTime(),
     recipients: input.recipients ?? [...(await plan.recipientsFor({ input: input.params, ctx }))],

package/src/fcm.ts

@@ -0,0 +1,211 @@
+// Single responsibility: one push to one Android device over FCM HTTP v1 — a service-account
+// assertion (RS256) exchanged for an OAuth access token, cached until shortly before it expires,
+// then the send, each under a deadline, and the answer read as delivered, gone or refused.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import { outbound } from '@ultimat3/core/outbound';
+import { t } from '@ultimat3/schema';
+import { signJwt } from './native-jwt';
+import type { NativeTransportDeps, ProviderRefusal } from './native-transport';
+import { refusalOf, signingKeyFrom } from './native-transport';
+import {
+  NotifyPushDeviceGoneError,
+  NotifyPushProviderRefusedError,
+  providerReason,
+} from './push-errors';
+import type { NativePush, NativeSender } from './push-message';
+import type { TokenCache } from './token-cache';
+import { tokenCache } from './token-cache';
+
+export interface FcmOptions {
+  /** The Firebase project id — the `project_id` of the service-account JSON. */
+  readonly projectId: string;
+  /** The service account's `client_email`. Its `private_key` is `ULTIMATE_FCM_PRIVATE_KEY`. */
+  readonly clientEmail: string;
+}
+
+export const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+export const FCM_ORIGIN = 'https://fcm.googleapis.com';
+export const FCM_SCOPE = 'https://www.googleapis.com/auth/firebase.messaging';
+
+/** The assertion's own life (Google's maximum), and how early a cached access token is replaced. */
+const ASSERTION_SECONDS = 3_600;
+export const FCM_TOKEN_REFRESH_BEFORE_MS = 5 * 60_000;
+
+const PROJECT = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+const CLIENT_EMAIL = /^[A-Za-z0-9._-]{1,128}@[a-z0-9.-]{1,128}$/;
+
+const AccessToken = t.object({ access_token: t.string.min(1), expires_in: t.number.int() });
+
+function screen(options: FcmOptions): void {
+  for (const [field, value, rule] of [
+    ['projectId', options.projectId, PROJECT],
+    ['clientEmail', options.clientEmail, CLIENT_EMAIL],
+  ] as const) {
+    if (!rule.test(value)) {
+      throw new ConfigInvalidError({
+        cause: `nativePush({ fcm }) ${field} is not what a Firebase service account carries`,
+        fix: `nativePush({ fcm: { projectId, clientEmail } })   # copy project_id and client_email from the service-account JSON`,
+        meta: { field },
+      });
+    }
+  }
+}
+
+/** The `message` the wire carries, built from `push` and nothing else. */
+export function fcmMessage(token: string, push: NativePush): Record<string, unknown> {
+  if (push.kind === 'data') {
+    // No `notification` block: Android hands the ids to the app and draws nothing.
+    return { token, data: { ...push.data }, android: { priority: 'high' } };
+  }
+  const { push: alert } = push;
+  return {
+    token,
+    notification: { title: alert.title, body: alert.body },
+    data: { url: alert.url },
+    android: {
+      priority: alert.urgent ? 'high' : 'normal',
+      ttl: `${String(alert.ttlSeconds)}s`,
+      ...(alert.collapse === undefined ? {} : { collapse_key: alert.collapse }),
+    },
+  };
+}
+
+/**
+ * FCM's dead-token answer: `UNREGISTERED` in the error's details. Never a bare 404 — a wrong
+ * `projectId` is a 404 too, and reading it as "gone" would delete every Android device the app
+ * has. The detail is cut at 200 characters, so a body too long to parse is searched as text.
+ */
+function isUnregistered(refusal: ProviderRefusal): boolean {
+  const details = (refusal.body?.['error'] as { details?: unknown } | undefined)?.details;
+  if (Array.isArray(details)) {
+    return details.some(
+      (entry: unknown) => (entry as { errorCode?: unknown } | null)?.errorCode === 'UNREGISTERED',
+    );
+  }
+  return refusal.body === undefined && refusal.detail.includes('"UNREGISTERED"');
+}
+
+const reasonOf = (body: Readonly<Record<string, unknown>> | undefined): string => {
+  const error = body?.['error'];
+  // The send API nests `{ error: { status } }`; the token endpoint answers `{ error: 'invalid_grant' }`.
+  return providerReason(
+    typeof error === 'string' ? error : (error as { status?: unknown })?.status,
+  );
+};
+
+/** The sentence FCM answers an unparseable token with — inside the first 200 characters. */
+const BAD_TOKEN_TEXT = 'not a valid FCM registration token';
+
+/**
+ * `INVALID_ARGUMENT` is a bad payload as often as a bad token, so only the `BadRequest` violation
+ * on `message.token` (or, in a detail cut too short to parse, FCM's own sentence for it) counts
+ * against the row: a payload bug must never delete every Android device the app has.
+ */
+function isBadToken(refusal: ProviderRefusal): boolean {
+  if (refusal.status !== 400) return false;
+  const details = (refusal.body?.['error'] as { details?: unknown } | undefined)?.details;
+  if (!Array.isArray(details)) {
+    return refusal.body === undefined && refusal.detail.includes(BAD_TOKEN_TEXT);
+  }
+  return details.some((entry: unknown) => {
+    const violations = (entry as { fieldViolations?: unknown } | null)?.fieldViolations;
+    return (
+      Array.isArray(violations) &&
+      violations.some(
+        (violation: unknown) =>
+          (violation as { field?: unknown } | null)?.field === 'message.token',
+      )
+    );
+  });
+}
+
+const refused = (
+  status: number,
+  reason: string,
+  flags: { credential?: boolean; badToken?: boolean } = {},
+) => new NotifyPushProviderRefusedError({ provider: 'fcm', status, reason, ...flags });
+
+export function fcmSender(options: FcmOptions, deps: NativeTransportDeps): NativeSender {
+  screen(options);
+  const wallMs = (): number => deps.clock.now().getTime();
+  const now = (): number => deps.clock.monotonic();
+  const access: TokenCache = tokenCache(
+    async () => {
+      const issuedAt = Math.floor(wallMs() / 1000);
+      const key = await signingKeyFrom(deps.env, 'fcm');
+      const assertion = await signJwt(
+        'RS256',
+        key,
+        { typ: 'JWT' },
+        {
+          iss: options.clientEmail,
+          scope: FCM_SCOPE,
+          aud: GOOGLE_TOKEN_URL,
+          iat: issuedAt,
+          exp: issuedAt + ASSERTION_SECONDS,
+        },
+      );
+      try {
+        const answer = await outbound(
+          {
+            url: GOOGLE_TOKEN_URL,
+            vendor: 'google-oauth',
+            dial: 'named',
+            deadlineMs: deps.deadlineMs,
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+              grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+              assertion,
+            }).toString(),
+          },
+          { fetch: deps.fetch, now },
+        );
+        const token = answer.json(AccessToken);
+        return { value: token.access_token, expiresAt: wallMs() + token.expires_in * 1000 };
+      } catch (error) {
+        const refusal = refusalOf(error);
+        if (refusal === undefined) throw error;
+        // Whatever the status, Google refusing the assertion is the service account's key.
+        throw refused(refusal.status, reasonOf(refusal.body), { credential: true });
+      }
+    },
+    wallMs,
+    FCM_TOKEN_REFRESH_BEFORE_MS,
+  );
+  const url = `${FCM_ORIGIN}/v1/projects/${options.projectId}/messages:send`;
+  return {
+    async send(token, push, signal) {
+      const body = JSON.stringify({ message: fcmMessage(token, push) });
+      const bearer = await access.get();
+      try {
+        await outbound(
+          {
+            url,
+            vendor: 'fcm',
+            dial: 'named',
+            deadlineMs: deps.deadlineMs,
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${bearer}` },
+            body,
+            signal,
+          },
+          { fetch: deps.fetch, now },
+        );
+      } catch (error) {
+        const refusal = refusalOf(error);
+        if (refusal === undefined) throw error;
+        if (isUnregistered(refusal)) {
+          throw new NotifyPushDeviceGoneError({
+            provider: 'fcm',
+            status: refusal.status,
+            reason: 'UNREGISTERED',
+          });
+        }
+        if (refusal.status === 401 || refusal.status === 403) access.invalidate(bearer);
+        throw refused(refusal.status, reasonOf(refusal.body), { badToken: isBadToken(refusal) });
+      }
+    },
+  };
+}

package/src/index.ts

@@ -7,6 +7,7 @@
 /** Re-exported so a `notifier` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
+export type { ApnsOptions } from './apns';
 export type { AttemptInput } from './attempt';
 export { attemptDelivery } from './attempt';
 export type {
@@ -21,7 +22,13 @@ export type { InAppChannelOptions } from './channel-in-app';
 export { IN_APP_CHANNEL, inAppChannel } from './channel-in-app';
 export type { MailChannelOptions, Mailer, NotifyMail } from './channel-mail';
 export { MAIL_CHANNEL, mailChannel } from './channel-mail';
-export type { NotifyPushMessage, PushChannelOptions, Pusher } from './channel-push';
+export type {
+  DataPushChannelOptions,
+  DataPusher,
+  NotifyPushMessage,
+  PushChannelOptions,
+  Pusher,
+} from './channel-push';
 export { PUSH_CHANNEL, pushChannel } from './channel-push';
 export type {
   DigestAppend,
@@ -47,6 +54,7 @@ export {
   NotifyFanoutTooWideError,
   NotifyStoreMissingError,
 } from './errors';
+export type { FcmOptions } from './fcm';
 // `runFanout` is deliberately absent, for the reason `registerJob` is absent from
 // @ultimat3/jobs: a second way to execute a fan-out would bypass the job the factory built, and
 // with it the retry policy, the cancellation and the manifest row.
@@ -59,6 +67,7 @@ export {
 } from './inbox-pg';
 export type {
   DeliveryClaim,
+  DeliveryClaimAnswer,
   DeliveryLedger,
   DeliveryRecord,
   DeliveryStatus,
@@ -66,6 +75,7 @@ export type {
   MemoryDeliveryLedgerOptions,
 } from './ledger';
 export {
+  DEFAULT_DELIVERY_RECLAIM_MS,
   DELIVERY_STATUSES,
   isDeliveryStatus,
   memoryDeliveryLedger,
@@ -75,6 +85,13 @@ export {
   postgresDeliveryLedger,
   SQL_NOTIFY_DELIVERIES_TABLE,
 } from './ledger-pg';
+export type { NativePusher, NativePushOptions } from './native-push';
+export {
+  DEFAULT_NATIVE_PUSH_DEADLINE_MS,
+  nativePush,
+  PUSH_BAD_TOKEN_LIMIT,
+} from './native-push';
+export { APNS_KEY_ENV, FCM_KEY_ENV } from './native-transport';
 export type { NotifyEvent, Recipient } from './notification';
 export { recipientSchema } from './notification';
 export type { NotifierDefinition } from './notifier';
@@ -93,6 +110,24 @@ export type {
 export { toDurationMs } from './plan';
 export type { MemoryPreferenceStore, PreferenceQuery, PreferenceStore } from './preferences';
 export { allowAllPreferences, memoryPreferenceStore } from './preferences';
+export type { PushDeviceRecord, PushDeviceStore, PushPlatform } from './push-device';
+export { memoryPushDeviceStore, PUSH_PLATFORMS } from './push-device';
+export type { PostgresPushDeviceStoreOptions } from './push-device-pg';
+export {
+  PUSH_DEVICES_TABLE,
+  postgresPushDeviceStore,
+  SQL_PUSH_DEVICES_TABLE,
+} from './push-device-pg';
+export type { PushProvider } from './push-errors';
+export {
+  NotifyPushDeviceGoneError,
+  NotifyPushMessageInvalidError,
+  NotifyPushProviderRefusedError,
+} from './push-errors';
+export type { PushData } from './push-message';
+export { DATA_PUSH_MAX_KEYS, DATA_PUSH_MAX_VALUE } from './push-message';
+export type { PushRegisterOptions } from './push-register';
+export { PUSH_DEVICES_PER_ACTOR, pushRegister, pushUnregister } from './push-register';
 export { purgeNotifyDeliveries, purgeNotifyDigests, purgeNotifyInbox } from './retention';
 export type { InstalledNotifyStores, NotifyStores } from './stores';
 export {

package/src/ledger-pg.ts

@@ -5,9 +5,9 @@
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
 import type { PgExecutor } from '@ultimat3/core';
-import { finiteCount } from '@ultimat3/core';
+import { finiteCount, uuidV7 } from '@ultimat3/core';
 import type { DeliveryClaim, DeliveryLedger, DeliveryRecord, DeliveryStatus } from './ledger';
-import { isDeliveryStatus } from './ledger';
+import { DEFAULT_DELIVERY_RECLAIM_MS, isDeliveryStatus } from './ledger';
 
 /**
  * Applied the way `SQL_JOBS_TABLE` and `SQL_IDEMPOTENCY_TABLE` are — by the boot, not by an app
@@ -36,25 +36,40 @@ create unique index if not exists x_notify_deliveries_claim_idx
   on x_notify_deliveries (notifier, key, channel, coalesce(recipient, ''));
 
 create index if not exists x_notify_deliveries_at_idx on x_notify_deliveries (at);
+
+alter table x_notify_deliveries add column if not exists claim_id uuid;
 `;
 
 /**
- * The claim, atomic in one statement. The `do update` fires ONLY for a row that is not already
- * `sent`, so a returned row always means this caller owns the delivery and must send. No row back
- * means the notification already went out and this attempt is a replay.
+ * The claim, atomic in one statement. The `do update` fires for a row that is not `sent` and not a
+ * live claim, so a returned row always means this caller owns the delivery and must send. No row
+ * back means it went out, or another attempt holds it: `SQL_NOTIFY_FIND` says which.
+ *
+ * `$7` is the job's clock minus the reclaim window, the rule `purgeExpired` states: `at` was written
+ * by whichever process took the delivery, so `now()` here would measure two clocks' offset.
  */
 export const SQL_NOTIFY_CLAIM = `
-insert into x_notify_deliveries (notifier, key, recipient, channel, status, attempts, at)
-values ($1, $2, $3, $4, 'sending', 1, $5)
+insert into x_notify_deliveries (notifier, key, recipient, channel, status, attempts, at, claim_id)
+values ($1, $2, $3, $4, 'sending', 1, $5, $6::uuid)
 on conflict (notifier, key, channel, coalesce(recipient, ''))
-do update set attempts = x_notify_deliveries.attempts + 1, status = 'sending', at = excluded.at
+do update set attempts = x_notify_deliveries.attempts + 1, status = 'sending', at = excluded.at,
+              claim_id = excluded.claim_id
 where x_notify_deliveries.status <> 'sent'
+  and (x_notify_deliveries.status <> 'sending' or x_notify_deliveries.at < $7)
 returning attempts
 `;
 
+/**
+ * `claim_id = $7 and status = 'sending'` is a FENCE, as on `SQL_IDEMPOTENCY_SETTLE`, and BOTH halves
+ * for the same reason: the id alone lets an attempt overwrite its own settlement, the status alone
+ * lets a straggler settle the row its reclaimer is sending. A row an older version left `sending`
+ * has no id, so nothing but a fresh claim settles it. `returning key` makes the refusal observable.
+ */
 export const SQL_NOTIFY_SETTLE = `
 update x_notify_deliveries set status = $5, at = $6
 where notifier = $1 and key = $2 and channel = $4 and coalesce(recipient, '') = coalesce($3, '')
+  and claim_id = $7::uuid and status = 'sending'
+returning key
 `;
 
 export const SQL_NOTIFY_FIND = `
@@ -114,6 +129,8 @@ export interface PostgresDeliveryLedgerOptions {
    * than by two defaults that happen to agree.
    */
   readonly windowMs?: number | undefined;
+  /** How long a `sending` row is held. Defaults to `DEFAULT_DELIVERY_RECLAIM_MS`; longer than your slowest send. */
+  readonly reclaimAfterMs?: number | undefined;
 }
 
 /** 24 hours — the same default `postgresIdempotencyStore` carries, for the reason above. */
@@ -140,6 +157,17 @@ export function postgresDeliveryLedger(
     options.windowMs ?? DEFAULT_DELIVERY_WINDOW_MS,
     1,
   );
+  const reclaimAfterMs = finiteCount(
+    'postgresDeliveryLedger',
+    'reclaimAfterMs',
+    options.reclaimAfterMs ?? DEFAULT_DELIVERY_RECLAIM_MS,
+    1,
+  );
+  const find = async (claim: DeliveryClaim): Promise<DeliveryRecord | undefined> => {
+    const rows = await executor.query<DeliveryRow>(SQL_NOTIFY_FIND, argsOf(claim));
+    const row = rows[0];
+    return row === undefined ? undefined : toRecord(row);
+  };
   return {
     windowMs,
     async purgeExpired(nowMs) {
@@ -153,20 +181,31 @@ export function postgresDeliveryLedger(
       return rows.length;
     },
     async claim(claim, at) {
+      const claimId = uuidV7();
       const rows = await executor.query<{ attempts: number }>(SQL_NOTIFY_CLAIM, [
         ...argsOf(claim),
         at,
+        claimId,
+        new Date(at.getTime() - reclaimAfterMs),
       ]);
-      return rows.length > 0;
+      if (rows.length > 0) return { outcome: 'owned', claimId };
+      // Two statements, and safe as two: `sent` never moves, and any other answer only retries. A
+      // row a sweep took meanwhile reads as held too, and the retry then claims it clean.
+      const found = await find(claim);
+      if (found?.status === 'sent') return { outcome: 'sent' };
+      const left = (found?.at.getTime() ?? at.getTime()) + reclaimAfterMs - at.getTime();
+      return { outcome: 'held', retryAfterMs: Math.max(0, left) };
     },
-    async settle(claim, status, at) {
-      await executor.query(SQL_NOTIFY_SETTLE, [...argsOf(claim), status, at]);
-    },
-    async find(claim) {
-      const rows = await executor.query<DeliveryRow>(SQL_NOTIFY_FIND, argsOf(claim));
-      const row = rows[0];
-      return row === undefined ? undefined : toRecord(row);
+    async settle(claim, status, at, claimId) {
+      const rows = await executor.query<{ key: string }>(SQL_NOTIFY_SETTLE, [
+        ...argsOf(claim),
+        status,
+        at,
+        claimId,
+      ]);
+      return rows.length > 0;
     },
+    find,
   };
 }
 

package/src/ledger.ts

@@ -5,7 +5,7 @@
 // replays the send. This is the second layer: the claim is taken atomically before the send, and a
 // claim that already reads `sent` answers `false` and the fan-out skips.
 
-import { finiteCount } from '@ultimat3/core';
+import { finiteCount, uuidV7 } from '@ultimat3/core';
 
 export const DELIVERY_STATUSES = ['sending', 'sent', 'failed'] as const;
 
@@ -39,21 +39,44 @@ export interface DeliveryRecord extends DeliveryClaim {
   readonly at: Date;
 }
 
+/**
+ * What a claim answers, and the three are three because each asks something different of the caller.
+ * `owned`: send, and settle under this id. `sent`: it went out, stop. `held`: a live attempt holds
+ * it. This attempt must NOT send and must NOT read that as `sent` either, or a holder that then dies
+ * is a notification nobody retries. `retryAfterMs` is what is left of the holder's window.
+ */
+export type DeliveryClaimAnswer =
+  | { readonly outcome: 'owned'; readonly claimId: string }
+  | { readonly outcome: 'sent' }
+  | { readonly outcome: 'held'; readonly retryAfterMs: number };
+
 export interface DeliveryLedger {
   /**
-   * Take ownership of this delivery. `true` means send; `false` means a completed row already
-   * exists and this attempt must not send.
+   * Take ownership of this delivery. A `failed` row is claimed at once.
    *
-   * A row left `sending` by a killed process IS re-claimable, deliberately: the alternative is a
-   * notification that silently never arrives because the process that owned it died. At-least-once
-   * is the guarantee this package offers and the honest one — `settle` is what closes the window.
+   * A row left `sending` IS re-claimable once its window has passed, deliberately: the alternative
+   * is a notification that silently never arrives because the process that owned it died. Inside
+   * the window it is `held`, so a second attempt running beside the first does not send too.
+   * At-least-once is the guarantee this package offers and the honest one: a send outlasting the
+   * window still overlaps its reclaimer.
    */
-  claim(claim: DeliveryClaim, at: Date): Promise<boolean>;
-  /** Record the outcome. Only `sent` blocks a future claim. */
-  settle(claim: DeliveryClaim, status: DeliveryStatus, at: Date): Promise<void>;
+  claim(claim: DeliveryClaim, at: Date): Promise<DeliveryClaimAnswer>;
+  /**
+   * Record the outcome, if `claimId` still owns the row and it is still `sending`. `false` means it
+   * did not, and nothing changed: a late attempt never moves its reclaimer's row, least of all from
+   * `sent` back to `failed`. Only `sent` blocks a future claim.
+   */
+  settle(claim: DeliveryClaim, status: DeliveryStatus, at: Date, claimId: string): Promise<boolean>;
   find(claim: DeliveryClaim): Promise<DeliveryRecord | undefined>;
 }
 
+/**
+ * How long a `sending` row belongs to the attempt that claimed it. Five minutes: past the 30 s a job
+ * lease survives a dead worker by, and past any send a provider SDK's own timeout allows. Too short
+ * is a duplicate send; too long is a crashed attempt's recipient waiting that much longer.
+ */
+export const DEFAULT_DELIVERY_RECLAIM_MS = 5 * 60 * 1000;
+
 /**
  * The tuple as one string. `JSON.stringify` of an ARRAY rather than a joined separator: a
  * recipient id or a channel name containing the separator would otherwise collide two distinct
@@ -70,6 +93,8 @@ export interface MemoryDeliveryLedgerOptions {
    * into the heap, and it says so by publishing `size`.
    */
   readonly max?: number;
+  /** How long a `sending` row is held. Defaults to `DEFAULT_DELIVERY_RECLAIM_MS`. */
+  readonly reclaimAfterMs?: number | undefined;
 }
 
 export const DEFAULT_MAX_DELIVERY_RECORDS = 10_000;
@@ -100,7 +125,13 @@ export function memoryDeliveryLedger(
     options.max ?? DEFAULT_MAX_DELIVERY_RECORDS,
     1,
   );
-  const rows = new Map<string, DeliveryRecord>();
+  const reclaimAfterMs = finiteCount(
+    'memoryDeliveryLedger',
+    'reclaimAfterMs',
+    options.reclaimAfterMs ?? DEFAULT_DELIVERY_RECLAIM_MS,
+    1,
+  );
+  const rows = new Map<string, { readonly record: DeliveryRecord; readonly claimId: string }>();
   let dropped = 0;
 
   const evict = (): void => {
@@ -121,28 +152,37 @@ export function memoryDeliveryLedger(
     },
     claim(claim, at) {
       const id = keyOf(claim);
-      const existing = rows.get(id);
-      if (existing?.status === 'sent') return Promise.resolve(false);
+      const existing = rows.get(id)?.record;
+      if (existing?.status === 'sent') return Promise.resolve({ outcome: 'sent' });
+      const reclaimAt = (existing?.at.getTime() ?? 0) + reclaimAfterMs;
+      if (existing?.status === 'sending' && at.getTime() <= reclaimAt) {
+        return Promise.resolve({ outcome: 'held', retryAfterMs: reclaimAt - at.getTime() });
+      }
+      const claimId = uuidV7();
       // The row it found keeps its own identity, as the pg `on conflict do update` does.
-      rows.set(id, {
+      const record: DeliveryRecord = {
         ...(existing ?? claim),
         status: 'sending',
         attempts: (existing?.attempts ?? 0) + 1,
         at,
-      });
+      };
+      rows.set(id, { record, claimId });
       evict();
-      return Promise.resolve(true);
+      return Promise.resolve({ outcome: 'owned', claimId });
     },
-    settle(claim, status, at) {
+    settle(claim, status, at, claimId) {
       const id = keyOf(claim);
       const existing = rows.get(id);
       // No claim, no row: the pg `update` matches nothing, and a row written here would refuse
       // the claim after it — a notification dev never sends and production does.
-      if (existing !== undefined) rows.set(id, { ...existing, status, at });
-      return Promise.resolve();
+      if (existing?.claimId !== claimId || existing.record.status !== 'sending') {
+        return Promise.resolve(false);
+      }
+      rows.set(id, { claimId, record: { ...existing.record, status, at } });
+      return Promise.resolve(true);
     },
     find(claim) {
-      return Promise.resolve(rows.get(keyOf(claim)));
+      return Promise.resolve(rows.get(keyOf(claim))?.record);
     },
     clear() {
       rows.clear();