@ultimat3/notify 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -2,9 +2,9 @@
 
 Tier 4. May import tiers 0-3. Never sideways, never upward.
 
-**Its real imports are `core`, `schema` (tier 0), `time` (tier 1) and `jobs` (tier 3), so tier 4 is
-its floor** — one above the highest tier it reaches. It sits AT that floor, so it has no
-`FLOOR_ABOVE` row and needs none. The import that fixes it there is `@ultimat3/jobs`: `notifier()`
+**Its real imports are `core`, `schema` (tier 0), `time`, `i18n` (tier 1), `policy` (tier 2),
+`action` and `jobs` (tier 3), so tier 4 is its floor** — one above the highest tier it reaches. It
+sits AT that floor, so it has no `FLOOR_ABOVE` row and needs none. The import that fixes it there is `@ultimat3/jobs`: `notifier()`
 returns a `job`, which is the whole design.
 
 ## What it may never import, and why
@@ -14,7 +14,13 @@ returns a `job`, which is the whole design.
 | `@ultimat3/mail` | Same tier (4). A `Mailer` is declared **structurally** in `channel-mail.ts` — one method, no dependency — exactly as `PgExecutor` (`@ultimat3/core`) mirrors `@ultimat3/db`. Moving `notify` to tier 5 to legalise the import would put notifications above `render`, `pwa` and `ui` for one channel's transport, and would then need a `cli → notify` edge the way `cli → scraping` does. |
 | `@ultimat3/render`, `@ultimat3/ui`, `@ultimat3/ai`, `@ultimat3/mcp`, `@ultimat3/pwa` | Same tier. A notification has no view — the inbox is rendered by the app's page out of `InboxStore.list`, which is data. `pushChannel` takes a STRUCTURAL `Pusher` (`channel-push.ts`), exactly as `mailChannel` takes a `Mailer`: `@ultimat3/pwa`'s `webPush()` satisfies it, and `NotifyPushMessage` mirrors pwa's `PushNotification` field for field — catalog keys, never text. |
 | `@ultimat3/db`, `@ultimat3/entity` | Legal downward, and deliberately not taken. The three tables this package owns are **DDL constants applied by the boot** (`SQL_NOTIFY_DELIVERIES_TABLE`, `SQL_NOTIFY_INBOX_TABLE`, `SQL_NOTIFY_DIGESTS_TABLE`), the way `x_jobs`, `x_idempotency` and `x_audit` are — never `entity()` declarations, which would put framework tables in the app's migration graph and make an app's `x db gen` responsible for them. The Postgres stores take a structural `PgExecutor`, imported as a **type** from `@ultimat3/core` (its one declaration; `bun run flight-copies` refuses another, `X_HELPER_COPY`). |
-| `@ultimat3/policy` | A notification is addressed to exactly one person and the audience is `recipients`. There is no row a policy could decide about here. The **inbox read surface** is where authz belongs, and that is the app's query. |
+| `@ultimat3/pwa` for native push | `nativePush()` (APNs + FCM) lives HERE, not in `pwa`: a native app is no progressive web app, and the pusher is `pushChannel`'s seam. It shares no code with `webPush()` — different wire, different auth, different store (`x_push_devices`, not `x_push_subscriptions`). |
+
+`@ultimat3/policy` and `@ultimat3/action` are taken for ONE file, `push-register.ts`: device
+registration is an action with a policy (`can()`, an agent denied), exactly as pwa's
+`pushSubscribe`. A notification itself still has no row a policy decides about — the audience is
+`recipients`, and the inbox read surface is the app's query. `pushRegister` / `pushUnregister` are
+factories over `action` and need rows in `PRIMITIVE_FACTORIES`.
 
 ## What ships, and what must never
 
@@ -53,6 +59,17 @@ A job body runs **before** its checkpoint lands, so both layers are load-bearing
    spellings against each other.
 
 `attempt.ts` is the only place a send happens, so there is exactly one implementation of that order.
+
+**A claim has one owner, and `held` is not `sent`** (`As of 2026-11-02`). `claim` answers
+`owned` (with a `claimId`), `sent` or `held`. A `sending` row fires only past `reclaimAfterMs`
+(`DEFAULT_DELIVERY_RECLAIM_MS`, 5 min, on the job's clock); `settle` is fenced `claim_id = $7 and
+status = 'sending'` as `SQL_IDEMPOTENCY_SETTLE` is, and `false` is logged `notify.settle_fenced`.
+`attemptDelivery` raises `held` as `X_NOTIFY_DELIVERY_HELD` (`retry-after`, the window's remainder
+in `meta.retryAfterSeconds`, deferred by jobs' `rateLimitDeferralMs` with the attempt uncounted) and
+never returns `false` for it: `false` checkpoints the step, and a
+holder that then dies is a notification no retry is left to send (`attempt.test.ts`,
+`ledger-parity.live.test.ts`).
+
 The **one at-most-once seam** is a digest flush: `DigestStore.drain` empties the window, and a
 process killed between the drain and its checkpoint loses that batch. It is stated in `digest.ts`
 rather than hidden. `postgresDigestStore` makes the window itself durable and shared — the
@@ -87,7 +104,7 @@ so an `open` checkpointed with duplicates by an earlier version is repaired on r
 | `fanout.ts` | the run body: audience, wait order, gates, delivery |
 | `fanout-digest.ts` · `fanout-walk.ts` | the digest branch, and the state both halves share |
 | `attempt.ts` | claim → send → settle, once |
-| `channel.ts` · `channel-in-app.ts` · `channel-mail.ts` · `channel-push.ts` | the seam and the three shipped channels |
+| `channel.ts` · `channel-in-app.ts` · `channel-mail.ts` · `channel-push.ts` | the seam and the three shipped channels; `pushChannel({ data })` is the data-only form, typed to a `DataPusher` so `webPush()` cannot take it |
 | `ledger.ts` · `ledger-pg.ts` | the delivery ledger, memory and Postgres |
 | `inbox.ts` · `inbox-pg.ts` | the in-app inbox, memory and Postgres |
 | `preferences.ts` · `digest.ts` | the gate and the window, as seams |
@@ -95,6 +112,13 @@ so an `open` checkpointed with duplicates by an earlier version is repaired on r
 | `stores.ts` | the one installer for all four |
 | `retention.ts` | the three sweeps, read off the installed seam |
 | `errors.ts` | this package's `X_NOTIFY_*` codes and their titles |
+| `native-push.ts` | `nativePush()`: every device of a person, dead tokens dropped, bad tokens counted, a credential refusal ending its provider's fan-out, refusals coded |
+| `apns.ts` · `fcm.ts` | one device's send per provider: credential, wire shape, answer |
+| `native-jwt.ts` · `token-cache.ts` · `native-transport.ts` | ES256/RS256 over WebCrypto; one credential per lifetime; the env key read and the refusal read back |
+| `push-message.ts` | a visible push rendered, a data-only push screened to ids |
+| `push-device.ts` · `push-device-pg.ts` | the device seam, memory and Postgres (`x_push_devices`) |
+| `push-register.ts` | `pushRegister` / `pushUnregister`, factories over `action` |
+| `push-errors.ts` | `X_NOTIFY_PUSH_*`, registered in `errors.ts` |
 
 One entry point, deliberately: every module runs on the server, so there is no browser half to split
 off.

package/README.md

@@ -3,6 +3,8 @@
 Notifications as one declaration: channel fan-out, a preference gate, a digest window, a delivery
 ledger and an in-app inbox.
 
+`bun add @ultimat3/notify` · guide: [Notify](https://github.com/developerz-ai/ultimate/wiki/Notify)
+
 `notifier()` is a **job factory** — it returns a `JobHandle`, so a notification inherits retry, the
 dead-letter path, cancellation, `x jobs show` and its manifest row. It is not a ninth primitive.
 
@@ -133,6 +135,13 @@ setNotifyStores({
 | `inbox` | **none** — `X_NOTIFY_STORE_MISSING` | a message written to nowhere is worse than a refusal |
 | `digest` | **none** — `X_NOTIFY_STORE_MISSING` | same. `memoryDigestStore()` for one process; `postgresDigestStore({ executor })` keeps a window across a restart and gives two replicas ONE window (a partial unique index on the open one), so exactly one run owns its flush |
 
+**One attempt owns a delivery.** `claim` answers `owned`, `sent` or `held`: a live `sending` row
+is held for `reclaimAfterMs` (`DEFAULT_DELIVERY_RECLAIM_MS`, 5 min; set it longer than your slowest
+send, on either ledger). A second attempt beside it sends nothing and raises `X_NOTIFY_DELIVERY_HELD`,
+and the job retries once the window has passed. `settle(claim, status, at, claimId)` answers `false`
+and changes nothing for an attempt that no longer owns the row. An app's own `DeliveryLedger`
+implements both.
+
 `executor` is a structural `{ query(sql, params) }` — `@ultimat3/db`'s `dbExecutor()` is the
 framework's own. `Bun.sql` does **not** satisfy it.
 
@@ -241,6 +250,75 @@ A recipient with no subscription is not a failure: the delivery settles, as `mai
 addressless recipient. A push service that answers 429 or 5xx throws `X_PWA_PUSH_FAILED` after every
 other device was tried, so the job retries; 404/410 deletes the subscription.
 
+### Native push — APNs and FCM
+
+`nativePush({ devices, apns, fcm })` is a pusher for iOS and Android apps, `As of 2026-11-06`: APNs
+token auth (an ES256 JWT over the team's `.p8` key, HTTP/2) and FCM HTTP v1 (an RS256
+service-account assertion exchanged for an OAuth token), both on WebCrypto through core's
+`outbound()` with a deadline — no SDK. Each credential is minted once and re-minted before it
+expires (APNs at 50 of its 60 minutes, Google's 5 minutes early); concurrent sends share one mint.
+
+```ts
+import {
+  memoryPushDeviceStore,
+  nativePush,
+  notifier,
+  pushChannel,
+  pushRegister,
+  t,
+} from '@ultimat3/notify';
+
+// `postgresPushDeviceStore({ executor: dbExecutor() })` in production: `x_push_devices`.
+const devices = memoryPushDeviceStore();
+
+// An action: its route, typed client, MCP tool and policy. Stored against `ctx.actor.id`.
+export const registerDevice = pushRegister({
+  permission: 'push:subscribe',
+  platforms: ['ios', 'android'],
+  devices,
+});
+
+const phones = nativePush({
+  devices,
+  apns: { teamId: 'TEAM123456', keyId: 'KEY1234567', topic: 'com.example.app' },
+  fcm: { projectId: 'example-app', clientEmail: 'push@example-app.iam.gserviceaccount.com' },
+});
+
+export const approvalRequested = notifier({
+  name: 'approval.requested',
+  input: t.object({ approvalId: t.uuid }),
+  tenant: 'none',
+  key: (params) => `approval:${params.approvalId}`,
+  deliver: [
+    // DATA-ONLY: the id, nothing a lock screen or the provider could read. The app wakes and
+    // fetches the rest over its own API.
+    {
+      channel: pushChannel<{ approvalId: string }>({
+        pusher: phones,
+        data: ({ event }) => ({ approvalId: event.params.approvalId }),
+      }),
+    },
+  ],
+});
+```
+
+| Piece | |
+|---|---|
+| private keys | never options: `ULTIMATE_APNS_PRIVATE_KEY` (the `.p8`) and `ULTIMATE_FCM_PRIVATE_KEY` (the service account's `private_key`), read from the environment when a token is minted — `x secrets set <name>` — and boxed in a `Secret` at once. Missing is `X_ENV_MISSING`, unreadable `X_CONFIG_INVALID`, each naming the variable and never its value |
+| registration | `pushRegister({ permission, platforms, devices })`; `previousToken` forgets the token the OS rotated away. `pushUnregister(…)` on sign-out — a token registered by a second person on the same phone is theirs now. Past `PUSH_DEVICES_PER_ACTOR` (20) the caller's oldest registration is evicted. An agent never registers. An iOS token is hex (it is spliced into the APNs path), an Android one FCM's alphabet — anything else is a 422 |
+| data-only | `pushChannel({ pusher, data })`: APNs `background` at priority 5 with `content-available: 1`, FCM with no `notification` block. At most 8 string keys, 256 characters each, no provider-reserved key (`aps`, `notification`, `google.*`…) — else `X_NOTIFY_PUSH_MESSAGE_INVALID` before a request. `webPush()` has no `sendData`, so handing it a `data` channel is a type error |
+| visible | `pushChannel({ pusher, message })` as for the web: title and body rendered per device locale; `url` travels as data; `topic ?? tag` is the collapse id; `urgency` low/very-low sends at the lower priority. `icon`, `badge`, `actions`, `requireInteraction`, `renotify` have no native meaning and are not sent |
+
+| Provider answer | What happens |
+|---|---|
+| 2xx | delivered |
+| APNs 410, FCM `UNREGISTERED` | `X_NOTIFY_PUSH_DEVICE_GONE`: the row is deleted, logged, and the delivery still settles. A bare FCM 404 is **not** gone (a wrong `projectId` is a 404 too) |
+| APNs 400 `BadDeviceToken`, FCM 400 `INVALID_ARGUMENT` on `message.token` | `X_NOTIFY_PUSH_PROVIDER_REFUSED` with `meta.badToken`; counted on the row, which is deleted on the `PUSH_BAD_TOKEN_LIMIT`th (3) answer in a row — never the first (`BadDeviceToken` is also a sandbox token sent to production). A delivery resets the count. An `INVALID_ARGUMENT` on the payload never counts |
+| 401/403, or Google refusing the assertion | `X_NOTIFY_PUSH_PROVIDER_REFUSED` with `meta.credential`: that provider's fan-out stops on its first device, the cached credential the refused request carried is dropped (only that one — a straggler's late 403 keeps a fresh token), and the refusal fails the delivery as `terminal` |
+| another 4xx | `X_NOTIFY_PUSH_PROVIDER_REFUSED`, logged; the next device is tried. When no device took it, the refusal fails the delivery |
+| 429, 5xx, timeout | rethrown after every other device was tried — the job's retry |
+
+
 ## The inbox
 
 ```ts
@@ -290,7 +368,10 @@ without bound and every replay would re-send the whole audience.
 | `X_NOTIFY_DIGEST_UNSUPPORTED` | a digest window on a bulk channel |
 | `X_NOTIFY_FANOUT_TOO_WIDE` | more recipients than `maxRecipients` (default 500) |
 | `X_NOTIFY_STORE_MISSING` | an inbox or digest channel with no store installed |
-| `X_NOTIFY_DELIVERY_FAILED` | a channel's `deliver` threw; the run retries on its policy |
+| `X_NOTIFY_DELIVERY_FAILED` | a channel's `deliver` threw; the run retries on its policy — unless the channel's error was classified `terminal` (`X_NOTIFY_PUSH_PROVIDER_REFUSED`, a mail provider's permanent refusal), which the wrapper keeps |
+| `X_NOTIFY_PUSH_DEVICE_GONE` | APNs 410 / FCM `UNREGISTERED`: the device row is deleted, nothing fails |
+| `X_NOTIFY_PUSH_PROVIDER_REFUSED` | APNs or FCM refused for good: a credential, a topic or project, a payload limit |
+| `X_NOTIFY_PUSH_MESSAGE_INVALID` | a data-only push carrying more than ids |
 
 ### Error classes
 
@@ -304,9 +385,20 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `NotifyDeliveryFailedError` | `X_NOTIFY_DELIVERY_FAILED` | `src/errors.ts` |
 | `NotifyDigestUnsupportedError` | `X_NOTIFY_DIGEST_UNSUPPORTED` | `src/errors.ts` |
 | `NotifyFanoutTooWideError` | `X_NOTIFY_FANOUT_TOO_WIDE` | `src/errors.ts` |
+| `NotifyPushDeviceGoneError` | `X_NOTIFY_PUSH_DEVICE_GONE` | `src/push-errors.ts` |
+| `NotifyPushMessageInvalidError` | `X_NOTIFY_PUSH_MESSAGE_INVALID` | `src/push-errors.ts` |
+| `NotifyPushProviderRefusedError` | `X_NOTIFY_PUSH_PROVIDER_REFUSED` | `src/push-errors.ts` |
 | `NotifyStoreMissingError` | `X_NOTIFY_STORE_MISSING` | `src/errors.ts` |
 
 ## Boundary
 
 Tier 4. May import tiers 0-3 — enforced by `bun run boundaries`. Its real imports are `core`,
-`schema`, `time` and `jobs`, so tier 4 is its floor. See [`CLAUDE.md`](./CLAUDE.md).
+`schema`, `i18n`, `time`, `policy`, `action` and `jobs`, so tier 4 is its floor. See [`CLAUDE.md`](./CLAUDE.md).
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `DeliveryClaimAnswer` | what `DeliveryLedger.claim` answers: `{ outcome: 'owned', claimId }`, `{ outcome: 'sent' }` or `{ outcome: 'held', retryAfterMs }` |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/notify",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "notifications",
+    "push",
+    "email",
+    "inbox"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Notify",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -35,9 +45,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/jobs": "29.3.2",
-    "@ultimat3/schema": "29.3.2",
-    "@ultimat3/time": "29.3.2"
+    "@ultimat3/action": "30.0.0",
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/i18n": "30.0.0",
+    "@ultimat3/jobs": "30.0.0",
+    "@ultimat3/policy": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/time": "30.0.0"
   }
 }

package/src/apns.ts

@@ -0,0 +1,145 @@
+// Single responsibility: one push to one iOS device over APNs — token auth (an ES256 JWT signed
+// with the team's `.p8` key, cached and re-signed before Apple's hour runs out), HTTP/2, a deadline
+// over the whole call, and the answer read as delivered, gone or refused.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import { outbound } from '@ultimat3/core/outbound';
+import { signJwt } from './native-jwt';
+import type { NativeTransportDeps } from './native-transport';
+import { http2, 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 ApnsOptions {
+  /** The 10-character Team ID the key belongs to. */
+  readonly teamId: string;
+  /** The 10-character Key ID of the `.p8` key in `ULTIMATE_APNS_PRIVATE_KEY`. */
+  readonly keyId: string;
+  /** The app's bundle id — `apns-topic`. */
+  readonly topic: string;
+  /** `sandbox` for a development build's tokens. Default `production`. */
+  readonly environment?: 'production' | 'sandbox' | undefined;
+}
+
+export const APNS_ORIGINS = {
+  production: 'https://api.push.apple.com',
+  sandbox: 'https://api.sandbox.push.apple.com',
+} as const;
+
+/** Apple refuses a token older than an hour and throttles one re-signed inside 20 minutes. */
+export const APNS_TOKEN_LIFETIME_MS = 60 * 60_000;
+export const APNS_TOKEN_REFRESH_BEFORE_MS = 10 * 60_000;
+
+const TEN = /^[A-Z0-9]{10}$/;
+const TOPIC = /^[A-Za-z0-9.-]{1,155}$/;
+
+function screen(options: ApnsOptions): void {
+  for (const [field, value, rule] of [
+    ['teamId', options.teamId, TEN],
+    ['keyId', options.keyId, TEN],
+    ['topic', options.topic, TOPIC],
+  ] as const) {
+    if (!rule.test(value)) {
+      throw new ConfigInvalidError({
+        cause: `nativePush({ apns }) ${field} is not what Apple issues (${String(rule)})`,
+        fix: `nativePush({ apns: { teamId, keyId, topic } })   # copy ${field} from the Apple developer account's Keys page or the app's bundle id`,
+        meta: { field },
+      });
+    }
+  }
+}
+
+/** The wire: headers and body built from `push` and nothing else. */
+export function apnsRequest(
+  push: NativePush,
+  topic: string,
+  nowSeconds: number,
+): { readonly headers: Record<string, string>; readonly body: string } {
+  if (push.kind === 'data') {
+    // Background: Apple requires priority 5 for it, and the app is woken with the ids alone.
+    return {
+      headers: { 'apns-topic': topic, 'apns-push-type': 'background', 'apns-priority': '5' },
+      body: JSON.stringify({ ...push.data, aps: { 'content-available': 1 } }),
+    };
+  }
+  const { push: alert } = push;
+  const headers: Record<string, string> = {
+    'apns-topic': topic,
+    'apns-push-type': 'alert',
+    'apns-priority': alert.urgent ? '10' : '5',
+    'apns-expiration': String(nowSeconds + alert.ttlSeconds),
+  };
+  if (alert.collapse !== undefined) headers['apns-collapse-id'] = alert.collapse;
+  return {
+    headers,
+    body: JSON.stringify({
+      aps: { alert: { title: alert.title, body: alert.body } },
+      url: alert.url,
+    }),
+  };
+}
+
+export function apnsSender(options: ApnsOptions, deps: NativeTransportDeps): NativeSender {
+  screen(options);
+  const origin = APNS_ORIGINS[options.environment ?? 'production'];
+  const wallMs = (): number => deps.clock.now().getTime();
+  const provider: TokenCache = tokenCache(
+    async () => {
+      const issuedAt = wallMs();
+      const key = await signingKeyFrom(deps.env, 'apns');
+      const value = await signJwt(
+        'ES256',
+        key,
+        { kid: options.keyId },
+        { iss: options.teamId, iat: Math.floor(issuedAt / 1000) },
+      );
+      return { value, expiresAt: issuedAt + APNS_TOKEN_LIFETIME_MS };
+    },
+    wallMs,
+    APNS_TOKEN_REFRESH_BEFORE_MS,
+  );
+  return {
+    async send(token, push, signal) {
+      const request = apnsRequest(push, options.topic, Math.floor(wallMs() / 1000));
+      const bearer = await provider.get();
+      try {
+        await outbound(
+          {
+            // The token was screened hex (`APNS_TOKEN`), so it cannot leave the path segment.
+            url: `${origin}/3/device/${token}`,
+            vendor: 'apns',
+            dial: 'named',
+            deadlineMs: deps.deadlineMs,
+            method: 'POST',
+            headers: { ...request.headers, authorization: `bearer ${bearer}` },
+            body: request.body,
+            signal,
+          },
+          { fetch: http2(deps.fetch), now: () => deps.clock.monotonic() },
+        );
+      } catch (error) {
+        const refusal = refusalOf(error);
+        if (refusal === undefined) throw error;
+        const reason = providerReason(refusal.body?.['reason']);
+        if (refusal.status === 410) {
+          throw new NotifyPushDeviceGoneError({ provider: 'apns', status: 410, reason });
+        }
+        // Expired or revoked provider token: the next send signs a fresh one.
+        if (refusal.status === 403) provider.invalidate(bearer);
+        throw new NotifyPushProviderRefusedError({
+          provider: 'apns',
+          status: refusal.status,
+          reason,
+          // Also a sandbox token sent to production, so counted per row, never read as gone.
+          badToken: refusal.status === 400 && reason === 'BadDeviceToken',
+        });
+      }
+    },
+  };
+}

package/src/attempt.ts

@@ -6,8 +6,9 @@
 // send that has not happened; claiming after would let two attempts pass the check together.
 
 import type { Ctx } from '@ultimat3/core';
-import { NotifyDeliveryFailedError } from './errors';
-import type { DeliveryClaim, DeliveryLedger } from './ledger';
+import { classifyThrown, logger } from '@ultimat3/core';
+import { NotifyDeliveryFailedError, NotifyDeliveryHeldError } from './errors';
+import type { DeliveryClaim, DeliveryLedger, DeliveryStatus } from './ledger';
 
 export interface AttemptInput {
   readonly ledger: DeliveryLedger;
@@ -18,7 +19,8 @@ export interface AttemptInput {
    * a bulk one. Reported in the refusal, because "the Slack post failed" and "one of 400 emails
    * failed" are different incidents. */
   readonly recipients: number;
-  readonly ctx: Ctx;
+  /** The job's clock, and nothing else: `send` closes over the rest. */
+  readonly ctx: Pick<Ctx, 'now'>;
   send(signal: AbortSignal): Promise<void> | void;
 }
 
@@ -26,23 +28,53 @@ export interface AttemptInput {
  * `true` when this attempt sent, `false` when the ledger already held a completed delivery — the
  * replay case, and the whole reason this function exists.
  *
+ * A claim another attempt holds raises `X_NOTIFY_DELIVERY_HELD`, never `false`: `false` checkpoints
+ * the step as done, and a holder that then dies is a notification no retry is left to send.
+ *
  * A throwing channel settles `failed` and then rethrows as `X_NOTIFY_DELIVERY_FAILED`: the row
  * stays re-claimable, so the job's own retry policy decides whether it goes out, and the dead
- * letter names the channel rather than whatever the provider's SDK threw.
+ * letter names the channel rather than whatever the provider's SDK threw. A channel error
+ * classified `terminal` (a provider refusing a credential for good) keeps that on the wrapper:
+ * read as `retryable`, every attempt re-sent the alert to each device that already took it.
  */
 export async function attemptDelivery(input: AttemptInput, signal: AbortSignal): Promise<boolean> {
-  if (!(await input.ledger.claim(input.claim, input.ctx.now()))) return false;
+  const answer = await input.ledger.claim(input.claim, input.ctx.now());
+  if (answer.outcome === 'sent') return false;
+  if (answer.outcome === 'held') {
+    throw new NotifyDeliveryHeldError({
+      notifier: input.notifier,
+      channel: input.channel,
+      retryAfterMs: answer.retryAfterMs,
+    });
+  }
+  const settle = async (status: DeliveryStatus): Promise<void> => {
+    const recorded = await input.ledger.settle(
+      input.claim,
+      status,
+      input.ctx.now(),
+      answer.claimId,
+    );
+    // The one trace of a send that outlasted its window: its reclaimer may have sent as well.
+    if (!recorded) {
+      logger.warn('notify.settle_fenced', {
+        notifier: input.notifier,
+        channel: input.channel,
+        status,
+      });
+    }
+  };
   try {
     await input.send(signal);
   } catch (error) {
-    await input.ledger.settle(input.claim, 'failed', input.ctx.now());
+    await settle('failed');
     throw new NotifyDeliveryFailedError({
       notifier: input.notifier,
       channel: input.channel,
       recipients: input.recipients,
       cause: error,
+      retry: classifyThrown(error) === 'terminal' ? 'terminal' : undefined,
     });
   }
-  await input.ledger.settle(input.claim, 'sent', input.ctx.now());
+  await settle('sent');
   return true;
 }

package/src/channel-push.ts

@@ -13,6 +13,9 @@
 //       tag: `post:${event.params.postId}`,
 //     }),
 //   })
+//
+// `nativePush()` (this package) satisfies it too, for iOS and Android, and adds the data-only
+// form: `pushChannel({ pusher: nativePush({ devices, apns, fcm }), data: ({ event }) => ({ id }) })`.
 
 import type { DeliveryArgs, NotifyChannel } from './channel';
 import { deliveryChannel } from './channel';
@@ -57,6 +60,21 @@ export interface Pusher {
   }): Promise<void> | void;
 }
 
+/**
+ * A pusher that can send a DATA-ONLY push — ids that wake the app and show nothing, on the lock
+ * screen or anywhere. `@ultimat3/notify`'s `nativePush()` is one; `webPush()` is not and cannot be
+ * (a browser push must show a notification), so handing it to `pushChannel({ data })` is a type
+ * error rather than a push that renders `undefined`.
+ */
+export interface DataPusher {
+  sendData(push: {
+    readonly to: string;
+    /** String ids only; screened by the transport (`X_NOTIFY_PUSH_MESSAGE_INVALID`). */
+    readonly data: Readonly<Record<string, string>>;
+    readonly signal: AbortSignal;
+  }): Promise<void> | void;
+}
+
 export const PUSH_CHANNEL = 'push';
 
 export interface PushChannelOptions<Params> {
@@ -69,19 +87,40 @@ export interface PushChannelOptions<Params> {
   readonly name?: string | undefined;
 }
 
+export interface DataPushChannelOptions<Params> {
+  readonly pusher: DataPusher;
+  /**
+   * The ids this push carries — and nothing a person would read: it crosses the provider and
+   * reaches the device unshown, and the app fetches the content over its own authenticated API.
+   */
+  readonly data: (args: DeliveryArgs<Params>) => Readonly<Record<string, string>>;
+  readonly name?: string | undefined;
+}
+
 /**
  * One delivery per recipient, to every device they subscribed. A recipient with no subscription is
  * NOT a failure — the pusher sends to nobody and the delivery settles, exactly as `mailChannel`
  * settles an addressless recipient: a retry would find the same empty list.
+ *
+ * With `data` instead of `message`, the push is data-only (`contentAvailable`): see `DataPusher`.
  */
 export function pushChannel<Params = unknown>(
   options: PushChannelOptions<Params>,
+): NotifyChannel<Params>;
+export function pushChannel<Params = unknown>(
+  options: DataPushChannelOptions<Params>,
+): NotifyChannel<Params>;
+export function pushChannel<Params = unknown>(
+  options: PushChannelOptions<Params> | DataPushChannelOptions<Params>,
 ): NotifyChannel<Params> {
-  return deliveryChannel<Params>(options.name ?? PUSH_CHANNEL, async (args) => {
-    await options.pusher.send({
-      to: args.recipient.id,
-      message: options.message(args),
-      signal: args.signal,
+  if ('data' in options) {
+    const { pusher, data } = options;
+    return deliveryChannel<Params>(options.name ?? PUSH_CHANNEL, async (args) => {
+      await pusher.sendData({ to: args.recipient.id, data: data(args), signal: args.signal });
     });
+  }
+  const { pusher, message } = options;
+  return deliveryChannel<Params>(options.name ?? PUSH_CHANNEL, async (args) => {
+    await pusher.send({ to: args.recipient.id, message: message(args), signal: args.signal });
   });
 }

package/src/errors.ts

@@ -3,6 +3,7 @@
 // No `docs:` line, and that is deliberate: `UltimateError`'s constructor resolves the registered
 // descriptor, whose default is `ERROR_DOCS_URL` in @ultimat3/core. A URL written out here is a
 // second answer to a question core already answers, and the last one went stale host and all.
+import type { ErrorRetry } from '@ultimat3/core';
 import {
   registerErrorCodes,
   registerErrorRetry,
@@ -17,6 +18,10 @@ export const NOTIFY_ERROR_CODES = [
   'X_NOTIFY_STORE_MISSING',
   'X_NOTIFY_DELIVERY_FAILED',
   'X_NOTIFY_DIGEST_UNSUPPORTED',
+  'X_NOTIFY_DELIVERY_HELD',
+  'X_NOTIFY_PUSH_DEVICE_GONE',
+  'X_NOTIFY_PUSH_PROVIDER_REFUSED',
+  'X_NOTIFY_PUSH_MESSAGE_INVALID',
 ] as const;
 
 export type NotifyErrorCode = (typeof NOTIFY_ERROR_CODES)[number];
@@ -28,6 +33,10 @@ export const NOTIFY_ERROR_TITLES: Readonly<Record<NotifyErrorCode, string>> = {
   X_NOTIFY_STORE_MISSING: 'a channel needs a store nothing installed',
   X_NOTIFY_DELIVERY_FAILED: 'a channel did not accept the delivery',
   X_NOTIFY_DIGEST_UNSUPPORTED: 'a digest window is declared on a bulk channel',
+  X_NOTIFY_DELIVERY_HELD: 'another attempt holds this delivery',
+  X_NOTIFY_PUSH_DEVICE_GONE: 'the push provider says a device token is dead',
+  X_NOTIFY_PUSH_PROVIDER_REFUSED: 'APNs or FCM refused a push for good',
+  X_NOTIFY_PUSH_MESSAGE_INVALID: 'a data-only push carries more than an id',
 };
 
 // One unconditional call, so a second package claiming one of notify's codes throws
@@ -66,6 +75,15 @@ registerErrorRetry({
   // declaring it is what makes that an answer rather than a coincidence, and what stops a later
   // sweep through this file from making the whole package terminal.
   X_NOTIFY_DELIVERY_FAILED: 'retryable',
+  // "Not yet": the holder finishes or its window lapses, and the refusal names how long that is.
+  // Waited out with the attempt uncounted and `maxDelay` no cap (`rateLimitDeferralMs`, jobs).
+  X_NOTIFY_DELIVERY_HELD: 'retry-after',
+  // Native push (`push-errors.ts`). A refusal the provider gives again — a bad credential, a wrong
+  // topic, a payload over its limit — and a data push carrying more than ids: no attempt fixes
+  // either. `X_NOTIFY_PUSH_DEVICE_GONE` is absent: `nativePush()` catches it, deletes the row, and
+  // it never leaves a send.
+  X_NOTIFY_PUSH_PROVIDER_REFUSED: 'terminal',
+  X_NOTIFY_PUSH_MESSAGE_INVALID: 'terminal',
 });
 
 /** Refused where it is written: a notifier with no channel is a job that fans out to nobody. */
@@ -158,6 +176,27 @@ export class NotifyDigestUnsupportedError extends UltimateError {
   }
 }
 
+/**
+ * A live attempt holds this delivery's claim. Never read as `sent`: that checkpoints the step, and a
+ * holder that then dies is a notification no retry is left to send. `retryAfterSeconds` is the one
+ * spelling a job's retry waits out, so the next attempt lands past the holder's window.
+ */
+export class NotifyDeliveryHeldError extends UltimateError {
+  constructor(input: { notifier: string; channel: string; retryAfterMs: number }) {
+    super({
+      code: 'X_NOTIFY_DELIVERY_HELD',
+      cause: `another attempt holds the "${input.channel}" delivery of notifier "${input.notifier}", so this one neither sent it nor counted it as sent; the claim can be reclaimed in ${String(input.retryAfterMs)} ms`,
+      fix: 'x jobs list --json   # the run retries on its own once the claim can be reclaimed; to shorten that, set reclaimAfterMs on postgresDeliveryLedger()',
+      meta: {
+        notifier: input.notifier,
+        channel: input.channel,
+        // One past the window: a retry landing exactly on its edge is still refused.
+        retryAfterSeconds: Math.ceil(input.retryAfterMs / 1_000) + 1,
+      },
+    });
+  }
+}
+
 /**
  * A channel's `deliver` threw. Wrapped rather than rethrown so the dead-letter row carries a
  * stable code and names the channel — a raw provider error names only itself.
@@ -166,9 +205,17 @@ export class NotifyDigestUnsupportedError extends UltimateError {
  * rejection is routinely an object whose `toString` throws (`bun run scripts/catch-render.ts`).
  */
 export class NotifyDeliveryFailedError extends UltimateError {
-  constructor(input: { notifier: string; channel: string; recipients: number; cause: unknown }) {
+  constructor(input: {
+    notifier: string;
+    channel: string;
+    recipients: number;
+    cause: unknown;
+    /** The channel's own `terminal`, carried over: absent, the code's `retryable` stands. */
+    retry?: ErrorRetry | undefined;
+  }) {
     super({
       code: 'X_NOTIFY_DELIVERY_FAILED',
+      retry: input.retry,
       cause: `channel "${input.channel}" of notifier "${input.notifier}" failed for ${String(input.recipients)} recipient(s): ${renderThrowable(input.cause)}`,
       // `x jobs list` first, and never `x jobs show` handed a notifier NAME: that command takes a job id
       // positional and resolves it through `inspectJob`, which answers `X_JOB_UNKNOWN` for