@takosjp/yurucommu-core 3.2.0 → 3.2.1

package/migrations/0019_notification_push_delivery.sql

@@ -1,3 +1,9 @@
+-- NO foreign keys on these tables. Cloudflare D1 ENFORCES declared FKs (see
+-- 0010/0011, which dropped the actors FKs for exactly that reason), local
+-- libsql runs with enforcement OFF, and the trigger below fires on EVERY
+-- unread inbox insert — an actors FK here would let a single missing actors
+-- row abort unrelated inbox writes in production only. Referential cleanup is
+-- app-level, like everywhere else (routes/account-teardown.ts).
 CREATE TABLE IF NOT EXISTS notification_pushers (
   id TEXT PRIMARY KEY,
   actor_ap_id TEXT NOT NULL,
@@ -15,13 +21,11 @@ CREATE TABLE IF NOT EXISTS notification_pushers (
   gateway_url TEXT NOT NULL,
   created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
   updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-  last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-  FOREIGN KEY (actor_ap_id) REFERENCES actors(ap_id) ON DELETE CASCADE
+  last_seen_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
 );
 
-CREATE UNIQUE INDEX IF NOT EXISTS notification_pushers_actor_product_app_pushkey_idx
-  ON notification_pushers(actor_ap_id, product, app_id, pushkey_hash);
-
+-- Device uniqueness is (product, app_id, pushkey_hash) — strictly stronger
+-- than any actor-scoped variant, so no second unique index is declared.
 CREATE INDEX IF NOT EXISTS notification_pushers_actor_product_idx
   ON notification_pushers(actor_ap_id, product);
 
@@ -44,8 +48,7 @@ CREATE TABLE IF NOT EXISTS notification_push_jobs (
   last_error TEXT,
   created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
   updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-  delivered_at TEXT,
-  FOREIGN KEY (actor_ap_id) REFERENCES actors(ap_id) ON DELETE CASCADE
+  delivered_at TEXT
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS notification_push_jobs_actor_activity_idx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [
@@ -32,8 +32,10 @@
     "packages/api/src/lib/api/moderation.ts",
     "packages/api/src/lib/api/notes.ts",
     "packages/api/src/lib/api/normalize.ts",
+    "packages/api/src/lib/api/notification-target.ts",
     "packages/api/src/lib/api/notifications.ts",
     "packages/api/src/lib/api/posts.ts",
+    "packages/api/src/lib/api/push-config.ts",
     "packages/api/src/lib/api/recommendations.ts",
     "packages/api/src/lib/api/search.ts",
     "packages/api/src/lib/api/stories.ts",
@@ -56,7 +58,8 @@
     "start": "bun src/backend/server.ts",
     "dev": "bun src/backend/server.ts",
     "dev:server": "bun src/backend/server.ts",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && bun run check:no-opentofu-artifacts",
+    "check:no-opentofu-artifacts": "bun scripts/check-no-opentofu-artifacts.mjs",
     "test": "bun run build:api && bun test test/ src/backend/ packages/api/src/ scripts/check-publish-version-discipline.test.ts scripts/publish-package-resumable.test.ts && bun run check:release-contents",
     "test:backend": "bun test src/backend/",
     "build": "bun run build:api",

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/packages/api/src/lib/api/browser-push.ts

@@ -294,6 +294,17 @@ function normalizeServerOrigin(value: string): string | null {
   }
 }
 
+/**
+ * Client-side gateway URL policy. MUST stay behaviorally equivalent to the
+ * server's `normalizeGatewayUrl` in the notification pusher contract — a
+ * client-accepted / server-rejected URL yields a confusing "registers but
+ * 400s" failure. The equivalence is pinned by a shared-fixture drift test.
+ * Exported for that test; app code calls the higher-level helpers above.
+ */
+export function normalizeBrowserPushGatewayUrl(value: string): string | null {
+  return normalizeGatewayUrl(value);
+}
+
 function normalizeGatewayUrl(value: string): string | null {
   try {
     const url = new URL(value.trim());

package/packages/api/src/lib/api/normalize.ts

@@ -6,6 +6,7 @@ import {
   Post,
   Story,
 } from "../../types/index.ts";
+import { resolveNotificationTarget } from "./notification-target.ts";
 
 type ActorLike = {
   ap_id: string;
@@ -71,7 +72,17 @@ export const normalizeActorNote = (note: ActorNote): ActorNote => ({
 
 export const normalizeNotification = (
   notification: Notification,
-): Notification => ({
-  ...notification,
-  actor: normalizeActor(notification.actor),
-});
+): Notification => {
+  // Fill the navigation target so consumers get a stable, safe same-origin
+  // path even from a pre-3.2.0 server that omitted target_* (or sent an unsafe
+  // target_url). resolveNotificationTarget re-validates a declared target and
+  // otherwise synthesizes it from type + object_ap_id.
+  const target = resolveNotificationTarget(notification);
+  return {
+    ...notification,
+    actor: normalizeActor(notification.actor),
+    target_kind: target.target_kind,
+    target_id: target.target_id,
+    target_url: target.target_url,
+  };
+};

package/packages/api/src/lib/api/notification-target.ts

@@ -0,0 +1,106 @@
+import type {
+  Notification,
+  NotificationTargetKind,
+} from "../../types/index.ts";
+
+export interface NotificationTarget {
+  readonly target_kind: NotificationTargetKind;
+  readonly target_id: string | null;
+  /**
+   * Same-origin in-app path shaped for the yurucommu web client's routing.
+   * Other clients should prefer `target_kind` + `target_id` and build their own
+   * path. Never treat this as an external URL.
+   */
+  readonly target_url: string;
+}
+
+/** True if the string contains any C0 control character (0x00-0x1f). */
+function hasControlChar(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    if (value.charCodeAt(index) < 0x20) return true;
+  }
+  return false;
+}
+
+/**
+ * Guard an in-app navigation path against open-redirect / protocol-relative /
+ * control-character abuse. Returns the value only if it is a plain same-origin
+ * absolute path (`/...`, not `//...`), else null. Promoted from the yurucommu
+ * and yurume web clients, which each carried an identical copy.
+ */
+export function safeNotificationPath(
+  value: string | null | undefined,
+): string | null {
+  if (
+    !value ||
+    !value.startsWith("/") ||
+    value.startsWith("//") ||
+    value.includes("\\") ||
+    hasControlChar(value)
+  ) {
+    return null;
+  }
+  return value;
+}
+
+function isStoryNotification(notification: Notification): boolean {
+  return (
+    notification.target_kind === "story" ||
+    !!notification.object_ap_id?.includes("/ap/stories/")
+  );
+}
+
+/**
+ * Resolve the navigation target for a notification. Prefers the server-provided
+ * `target_*` fields (3.2.0+) after re-validating `target_url`; when a server
+ * older than 3.2.0 omitted them, synthesizes the same mapping the server uses
+ * from `type` + `object_ap_id`. Always returns a safe same-origin path.
+ */
+export function resolveNotificationTarget(
+  notification: Notification,
+): NotificationTarget {
+  const declaredKind = notification.target_kind;
+  const declaredUrl = safeNotificationPath(notification.target_url);
+  if (declaredKind && declaredUrl) {
+    return {
+      target_kind: declaredKind,
+      target_id: notification.target_id ?? null,
+      target_url: declaredUrl,
+    };
+  }
+
+  if (
+    notification.type === "follow" ||
+    notification.type === "follow_request"
+  ) {
+    const actorApId = notification.actor?.ap_id ?? null;
+    return {
+      target_kind: "profile",
+      target_id: actorApId,
+      target_url: actorApId
+        ? `/profile/${encodeURIComponent(actorApId)}`
+        : "/notifications",
+    };
+  }
+
+  const objectApId = notification.object_ap_id;
+  if (objectApId && isStoryNotification(notification)) {
+    return {
+      target_kind: "story",
+      target_id: objectApId,
+      target_url: `/?story=${encodeURIComponent(objectApId)}`,
+    };
+  }
+  if (objectApId) {
+    return {
+      target_kind: "post",
+      target_id: objectApId,
+      target_url: `/post/${encodeURIComponent(objectApId)}`,
+    };
+  }
+  return {
+    target_kind: "notifications",
+    target_id: null,
+    target_url: "/notifications",
+  };
+}

package/packages/api/src/lib/api/push-config.ts

@@ -0,0 +1,132 @@
+import type { NotificationPusherProduct } from "../../types/index.ts";
+import {
+  clearBrowserNotificationPush,
+  disableBrowserNotificationPush,
+  type BrowserNotificationPushConfig,
+} from "./browser-push.ts";
+import { fetchNotificationPusherPublicConfig } from "./notifications.ts";
+
+/**
+ * Stable identity of a browser/PWA push client. Everything here is a per-app
+ * constant; only the gateway URL, VAPID key, and server origin are resolved at
+ * runtime.
+ */
+export interface BrowserPushClientIdentity {
+  readonly product: NotificationPusherProduct;
+  readonly appId: string;
+  readonly appDisplayName: string;
+  /** Root-relative service worker script path (e.g. "/notification-push-sw.js"). */
+  readonly serviceWorkerPath: string;
+  readonly scope?: string;
+  readonly lang?: string;
+}
+
+/** Non-secret runtime gateway values, from a fetch or build-time fallback. */
+export interface BrowserPushRuntimeValues {
+  readonly gatewayUrl?: string | null;
+  readonly vapidPublicKey?: string | null;
+}
+
+export interface BrowserPushConfigResolverOptions {
+  readonly identity: BrowserPushClientIdentity;
+  /**
+   * Origin of the yurucommu-compatible API that owns the registration. Returns
+   * null when it cannot be determined (e.g. SSR, or an unconfigured shell), in
+   * which case config resolution yields null.
+   */
+  readonly resolveServerOrigin: () => string | null;
+  /**
+   * Build-time fallback used only while a server rolls forward to 3.2.0; a
+   * responding runtime config always wins.
+   */
+  readonly buildTimeValues?: () => BrowserPushRuntimeValues | null;
+}
+
+export interface BrowserPushConfigResolver {
+  /** Build config from build-time values only (no network). */
+  readonly buildTimeConfig: () => BrowserNotificationPushConfig | null;
+  /**
+   * Resolve config from the server's runtime pusher config, falling back to
+   * build-time values if the server is unreachable or has push disabled.
+   */
+  readonly resolveConfig: () => Promise<BrowserNotificationPushConfig | null>;
+  /**
+   * Invalidate this device's endpoint before sign-out / account teardown,
+   * disabling via the resolved config when possible and always clearing the
+   * local subscription so a signed-out device is never woken.
+   */
+  readonly clearBeforeSignOut: () => Promise<void>;
+}
+
+/**
+ * Build a browser push config resolver for a single client identity. Promoted
+ * from the near-identical per-app resolvers in the yurucommu and yurume web
+ * clients so the fetch/fallback/clear flow lives in one place.
+ */
+export function createBrowserPushConfigResolver(
+  options: BrowserPushConfigResolverOptions,
+): BrowserPushConfigResolver {
+  const { identity, resolveServerOrigin, buildTimeValues } = options;
+
+  const build = (
+    values: BrowserPushRuntimeValues | null | undefined,
+  ): BrowserNotificationPushConfig | null => {
+    const gatewayUrl = values?.gatewayUrl?.trim();
+    const vapidPublicKey = values?.vapidPublicKey?.trim();
+    if (!gatewayUrl || !vapidPublicKey) return null;
+    const serverOrigin = resolveServerOrigin();
+    if (!serverOrigin) return null;
+    return {
+      product: identity.product,
+      appId: identity.appId,
+      appDisplayName: identity.appDisplayName,
+      serverOrigin,
+      gatewayUrl,
+      vapidPublicKey,
+      serviceWorkerPath: identity.serviceWorkerPath,
+      ...(identity.scope ? { scope: identity.scope } : {}),
+      ...(identity.lang ? { lang: identity.lang } : {}),
+    };
+  };
+
+  const buildTimeConfig = (): BrowserNotificationPushConfig | null =>
+    build(buildTimeValues?.() ?? null);
+
+  const resolveConfig =
+    async (): Promise<BrowserNotificationPushConfig | null> => {
+      try {
+        const runtime = await fetchNotificationPusherPublicConfig();
+        if (
+          !runtime.enabled ||
+          !runtime.gateway_url ||
+          !runtime.web_push_public_key
+        ) {
+          return null;
+        }
+        return build({
+          gatewayUrl: runtime.gateway_url,
+          vapidPublicKey: runtime.web_push_public_key,
+        });
+      } catch {
+        // Compatibility with older servers while they roll forward. Build-time
+        // public values are a fallback only; a responding runtime config is the
+        // deployment authority.
+        return buildTimeConfig();
+      }
+    };
+
+  const clearBeforeSignOut = async (): Promise<void> => {
+    const config = await resolveConfig().catch(() => null);
+    if (config) {
+      try {
+        await disableBrowserNotificationPush(config);
+        return;
+      } catch {
+        // Fall through to local endpoint invalidation.
+      }
+    }
+    await clearBrowserNotificationPush(identity).catch(() => undefined);
+  };
+
+  return { buildTimeConfig, resolveConfig, clearBeforeSignOut };
+}

package/packages/api/src/lib/api.ts

@@ -7,7 +7,9 @@ export * from "./api/posts.ts";
 export * from "./api/communities.ts";
 export * from "./api/dm.ts";
 export * from "./api/notifications.ts";
+export * from "./api/notification-target.ts";
 export * from "./api/browser-push.ts";
+export * from "./api/push-config.ts";
 export * from "./api/search.ts";
 export * from "./api/media.ts";
 export * from "./api/stories.ts";

package/packages/api/src/social-server.ts

@@ -16,6 +16,11 @@ export interface SocialServerDiscovery {
     readonly defaultEntry: "feed" | "messages";
   }[];
   readonly issuer: string;
+  readonly oidcClientId?: string;
+  readonly auth?: {
+    readonly oidc: boolean;
+    readonly password: boolean;
+  };
   readonly apiBaseUrl: string;
   readonly activitypubOrigin: string;
   readonly mediaOrigin: string;
@@ -24,6 +29,8 @@ export interface SocialServerDiscovery {
   readonly endpoints: {
     readonly api: string;
     readonly authProviders: string;
+    readonly mobilePasswordLogin: string;
+    readonly mobileOidcExchange: string;
     readonly currentUser: string;
     readonly timeline: string;
     readonly conversations: string;

package/packages/api/src/types/index.ts

@@ -122,14 +122,23 @@ export interface Notification {
   type: "follow" | "follow_request" | "like" | "announce" | "reply" | "mention";
   actor: NotificationActor;
   object_ap_id: string | null;
-  target_kind: "post" | "story" | "profile" | "community" | "notifications";
-  target_id: string | null;
-  /** Same-origin in-app path. Clients must not treat this as an external URL. */
-  target_url: string;
+  /**
+   * Navigation target for the notification. OPTIONAL: a server older than
+   * 3.2.0 omits these fields, and `normalizeNotification` then synthesizes them
+   * from `object_ap_id`. Prefer `target_kind` + `target_id` and build your own
+   * in-app path; `target_url` is shaped for the yurucommu web client's routing
+   * and is same-origin only — never treat it as an external URL.
+   */
+  target_kind?: NotificationTargetKind;
+  target_id?: string | null;
+  target_url?: string;
   read: boolean;
   created_at: string;
 }
 
+export type NotificationTargetKind =
+  "post" | "story" | "profile" | "notifications";
+
 export type NotificationPusherProduct = "yurucommu" | "yurume";
 
 export interface NotificationPusherInput {

package/src/backend/index.ts

@@ -219,6 +219,7 @@ function buildSocialServerDiscovery(
   appUrl: string,
   issuer: string,
   options: YurucommuBackendDiscoveryOptionsV1 = {},
+  auth: { oidcClientId?: string; passwordEnabled?: boolean } = {},
 ) {
   const discovery = {
     ...DEFAULT_DISCOVERY_OPTIONS,
@@ -238,6 +239,11 @@ function buildSocialServerDiscovery(
     },
     clients: discovery.clients,
     issuer,
+    oidcClientId: auth.oidcClientId,
+    auth: {
+      oidc: Boolean(auth.oidcClientId),
+      password: Boolean(auth.passwordEnabled),
+    },
     apiBaseUrl: appUrl,
     activitypubOrigin: appUrl,
     mediaOrigin: `${appUrl}/media`,
@@ -246,6 +252,8 @@ function buildSocialServerDiscovery(
     endpoints: {
       api: `${appUrl}/api`,
       authProviders: `${appUrl}/api/auth/providers`,
+      mobilePasswordLogin: `${appUrl}/api/auth/mobile/login`,
+      mobileOidcExchange: `${appUrl}/api/auth/mobile/oidc`,
       currentUser: `${appUrl}/api/auth/me`,
       timeline: `${appUrl}/api/timeline`,
       conversations: `${appUrl}/api/dm/contacts`,
@@ -331,9 +339,19 @@ function mountReadinessRoutes(
   ) => {
     const appUrl = normalizeOrigin(c.env.APP_URL, c.req.url);
     const issuer = getOidcIssuerUrl(c.env) ?? appUrl;
-    return c.json(buildSocialServerDiscovery(appUrl, issuer, discovery), 200, {
-      "Cache-Control": "public, max-age=300",
-    });
+    const { clientId } = getOidcClientCredentials(c.env);
+    return c.json(
+      buildSocialServerDiscovery(appUrl, issuer, discovery, {
+        oidcClientId: getOidcIssuerUrl(c.env)
+          ? clientId || undefined
+          : undefined,
+        passwordEnabled: Boolean(c.env.AUTH_PASSWORD_HASH?.trim()),
+      }),
+      200,
+      {
+        "Cache-Control": "public, max-age=300",
+      },
+    );
   };
 
   app.get("/.well-known/yurucommu", wellKnownSocialServer);
@@ -564,14 +582,31 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
     const recoveryDue = now - lastNotificationPushRecoverySweep >= 60_000;
     if (mutating || recoveryDue) {
       if (recoveryDue) lastNotificationPushRecoverySweep = now;
+      const sweep = (async () => {
+        try {
+          await enqueuePendingNotificationPushJobs(c.env);
+        } catch (error) {
+          log.error("Failed to enqueue notification push outbox", {
+            event: "notification.push.enqueue_failed",
+            error,
+          });
+        }
+      })();
+      // Prefer to run the sweep AFTER the response is sent (waitUntil) so its
+      // 2-4 D1 round-trips never add latency to the request. `executionCtx`
+      // throws when no runtime context exists (tests / plain fetch); fall back
+      // to awaiting inline there.
+      let deferred = false;
       try {
-        await enqueuePendingNotificationPushJobs(c.env);
-      } catch (error) {
-        log.error("Failed to enqueue notification push outbox", {
-          event: "notification.push.enqueue_failed",
-          error,
-        });
+        const ctx = c.executionCtx;
+        if (ctx && typeof ctx.waitUntil === "function") {
+          ctx.waitUntil(sweep);
+          deferred = true;
+        }
+      } catch {
+        // No execution context; await inline below.
       }
+      if (!deferred) await sweep;
     }
   });
 

package/src/backend/lib/attachments.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared attachment bounds + validation.
+ *
+ * Owner of the attachment payload limits used by every write surface (post
+ * create, DM messages, community chat) and by inbound-federation bounding.
+ * Route files must import from here instead of copy-pasting the checks or
+ * reaching into another route's transformers module.
+ */
+
+// Bound the attachments payload. An attachment is an open-ended record, so cap
+// both the COUNT and the serialized SIZE — the size cap bounds row/federated-doc
+// bloat regardless of internal shape (key count / field length). 16 KiB is ample
+// for MAX_ATTACHMENTS media descriptors with alt text + blurhash.
+export const MAX_ATTACHMENTS = 8;
+export const MAX_ATTACHMENTS_JSON_LENGTH = 16 * 1024;
+
+/** Drop an oversized inbound attachments blob to "[]" rather than store it. */
+export function boundAttachmentsJson(json: string): string {
+  return json.length > MAX_ATTACHMENTS_JSON_LENGTH ? "[]" : json;
+}
+
+export type ChatAttachment = Record<string, unknown>;
+
+export type ChatAttachmentsResult =
+  | { readonly ok: true; readonly attachments: ChatAttachment[] }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * Validate a chat message's attachments array (mirrors the post-create bounds:
+ * records only, capped count + serialized size). Returns the validated array
+ * ([] when absent) or an error message. Used by both the DM and community-chat
+ * send routes so the two cannot drift.
+ */
+export function validateChatAttachments(raw: unknown): ChatAttachmentsResult {
+  if (raw === undefined || raw === null) return { ok: true, attachments: [] };
+  if (!Array.isArray(raw)) {
+    return { ok: false, error: "attachments must be an array" };
+  }
+  if (raw.some((a) => !a || typeof a !== "object" || Array.isArray(a))) {
+    return { ok: false, error: "attachments must be objects" };
+  }
+  if (raw.length > MAX_ATTACHMENTS) {
+    return {
+      ok: false,
+      error: `Too many attachments (max ${MAX_ATTACHMENTS})`,
+    };
+  }
+  if (JSON.stringify(raw).length > MAX_ATTACHMENTS_JSON_LENGTH) {
+    return { ok: false, error: "attachments payload too large" };
+  }
+  return { ok: true, attachments: raw as ChatAttachment[] };
+}

package/src/backend/lib/delivery/queue.ts

@@ -24,6 +24,7 @@ import { filterBlockedActorApIds, isActorBlocked } from "../blocklist.ts";
 import {
   enqueuePendingNotificationPushJobs,
   processNotificationPushJob,
+  recoverDeadLetteredNotificationPushJob,
 } from "../notification-push.ts";
 
 const log = logger.child({ component: "delivery.queue" });
@@ -539,10 +540,21 @@ export async function handleDeliveryDlqBatch(
   for (const message of batch.messages) {
     const body = message.body;
     if (!isDeliveryDlqMessageV1(body)) {
+      // Not an app-built `dlq` message. Cloudflare Queues also delivers here
+      // the RAW original body of any MAIN-queue message that exhausted its
+      // retries (automatic dead-lettering). Those must NOT be silently acked as
+      // "invalid": a lost fanout/resolve drops local notifications or delivery
+      // planning, and a lost notification_push strands its durable outbox row.
+      if (isDeliveryQueueMessageV1(body)) {
+        await handleAutoDeadLetteredMessage(env, body);
+        message.ack();
+        continue;
+      }
       log.warn("Invalid DLQ message format, skipping", {
         event: "delivery.dlq.invalid_message",
         bodyPreview: JSON.stringify(body).slice(0, 200),
       });
+      emitMetric("delivery.dlq.invalid_message", 1, {});
       message.ack();
       continue;
     }
@@ -592,3 +604,46 @@ export async function handleDeliveryDlqBatch(
     message.ack();
   }
 }
+
+/**
+ * Recover / account for a MAIN-queue message that Cloudflare auto-dead-lettered
+ * (retries exhausted with the raw body). `notification_push` rows are durable,
+ * so reset the job to retry through the outbox instead of stranding it;
+ * everything else is logged with an alerting metric rather than swallowed.
+ */
+async function handleAutoDeadLetteredMessage(
+  env: Env,
+  body: DeliveryQueueMessageV1,
+): Promise<void> {
+  if (body.type === "notification_push") {
+    try {
+      const recovered = await recoverDeadLetteredNotificationPushJob(
+        env.DB_INSTANCE,
+        body.jobId,
+      );
+      log.error("notification_push dead-lettered; reset durable outbox row", {
+        event: "delivery.dlq.notification_push_recovered",
+        jobId: body.jobId,
+        recovered,
+      });
+      emitMetric("delivery.dlq.notification_push_recovered", 1, {});
+    } catch (error) {
+      log.error("Failed to recover dead-lettered notification_push", {
+        event: "delivery.dlq.notification_push_recover_failed",
+        jobId: body.jobId,
+        error,
+      });
+      emitMetric("delivery.dlq.notification_push_recover_failed", 1, {});
+    }
+    return;
+  }
+
+  // fanout_*/resolve_actor/deliver_endpoint/reconcile_job: no durable ledger to
+  // rewind here, but make the loss explicit (alertable) rather than a silent
+  // "invalid message" ack.
+  log.error("Delivery message auto-dead-lettered; dropping", {
+    event: "delivery.dlq.auto_dead_lettered",
+    messageType: body.type,
+  });
+  emitMetric("delivery.dlq.auto_dead_lettered", 1, { message_type: body.type });
+}