@takosjp/yurucommu-core 3.2.0 → 3.3.0

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

@@ -0,0 +1,306 @@
+/**
+ * Call signaling wire contract (voice + video).
+ *
+ * SINGLE SOURCE OF TRUTH shared by:
+ *   - the backend cross-instance signaling ingest (`/ap/rtc/signal`) + the
+ *     Signaling Durable Object (server-to-server + browser fan-out), and
+ *   - the browser `CallClient` (`../lib/rtc-client.ts`).
+ *
+ * Kept deliberately DOM-structural (no `RTCIceCandidateInit` / `RTCIceServer`
+ * imports) so the same file type-checks in the server context (which never runs
+ * the browser WebRTC APIs) and the browser bundle. The `CallClient` maps these
+ * structural shapes to/from the real DOM `RTCSessionDescriptionInit` /
+ * `RTCIceCandidateInit` / `RTCIceServer`, which are structurally compatible.
+ *
+ * Design: signaling travels over federation (server-to-server, HTTP-Signature
+ * authenticated) as `RtcSignalEnvelopeV1`; media is P2P WebRTC + STUN/TURN for
+ * 1:1 (`sfuFocus: null`) and a pluggable WHIP/WHEP SFU focus for group calls.
+ */
+
+export const RTC_SIGNAL_ENVELOPE_VERSION = 1 as const;
+
+/** Which media tracks a call carries. `video:false` => audio-only call. */
+export interface CallMediaKind {
+  audio: boolean;
+  video: boolean;
+}
+
+/** Cross-instance signaling message kinds (Matrix-VoIP inspired). */
+export type RtcSignalType =
+  | "offer"
+  | "answer"
+  | "candidate"
+  | "accept"
+  | "reject"
+  | "hangup"
+  | "cancel";
+
+/**
+ * Selected SFU focus for a group call. `null`/absent means pure P2P (1:1).
+ * `kind` names the adapter (`whip` / `livekit` / `cloudflare-realtime` / ...);
+ * the client talks WHIP/WHEP so the SFU backend stays vendor-neutral.
+ */
+export interface SfuFocus {
+  kind: string;
+  /** WHIP (publish) / WHEP (subscribe) endpoint base, or SFU signaling URL. */
+  url: string;
+  /** Short-lived join token when the adapter requires one. */
+  token?: string;
+  room?: string;
+}
+
+/** Structural mirror of `RTCIceCandidateInit` (no DOM dependency). */
+export interface CallIceCandidate {
+  candidate: string;
+  sdpMid?: string | null;
+  sdpMLineIndex?: number | null;
+  usernameFragment?: string | null;
+}
+
+/** Structural mirror of `RTCIceServer` (no DOM dependency). */
+export interface IceServerConfig {
+  urls: string | string[];
+  username?: string;
+  credential?: string;
+}
+
+/**
+ * Server-to-server signaling envelope. Delivered by the sending instance to the
+ * recipient instance's `/ap/rtc/signal` endpoint, signed with the sender actor's
+ * HTTP Signature key (keyId-owner === `from`). `callId` doubles as the anti-
+ * replay nonce; `ts`/`ttlMs` bound its freshness (the DO drops stale frames).
+ */
+export interface RtcSignalEnvelopeV1 {
+  v: typeof RTC_SIGNAL_ENVELOPE_VERSION;
+  callId: string;
+  from: string;
+  to: string;
+  type: RtcSignalType;
+  media?: CallMediaKind;
+  /** SDP for `offer` / `answer`. */
+  sdp?: string;
+  /** Half-trickle ICE bundle for `offer` / `answer` / `candidate`. */
+  candidates?: CallIceCandidate[];
+  sfuFocus?: SfuFocus | null;
+  /** Free-text end/reject reason (`busy`, `declined`, `timeout`, ...). */
+  reason?: string;
+  ts: number;
+  ttlMs: number;
+}
+
+/** Lifecycle of a single call, mirrored client-side and in `call_sessions`. */
+export type CallState =
+  | "idle"
+  | "ringing"
+  | "connecting"
+  | "connected"
+  | "ended"
+  | "rejected"
+  | "missed"
+  | "failed"
+  | "cancelled";
+
+export type CallDirection = "incoming" | "outgoing";
+
+/** Terminal states — a call in one of these is over and not resumable. */
+export const TERMINAL_CALL_STATES: readonly CallState[] = [
+  "ended",
+  "rejected",
+  "missed",
+  "failed",
+  "cancelled",
+];
+
+export function isTerminalCallState(state: CallState): boolean {
+  return TERMINAL_CALL_STATES.includes(state);
+}
+
+// ---------------------------------------------------------------------------
+// Browser <-> Signaling Durable Object WebSocket frames
+// ---------------------------------------------------------------------------
+
+/** Frames the browser sends up to its own instance's Signaling DO. */
+export type ClientToHubFrame =
+  | { t: "hello" }
+  | { t: "invite"; callId: string; to: string; media: CallMediaKind }
+  | { t: "offer"; callId: string; sdp: string }
+  | { t: "answer"; callId: string; sdp: string }
+  | { t: "candidates"; callId: string; candidates: CallIceCandidate[] }
+  | { t: "accept"; callId: string }
+  | { t: "reject"; callId: string; reason?: string }
+  | { t: "hangup"; callId: string; reason?: string }
+  | { t: "resume"; callId: string }
+  | { t: "ping" };
+
+/** Frames the Signaling DO pushes down to the browser. */
+export type HubToClientFrame =
+  | { t: "ready" }
+  | { t: "ringing"; callId: string; from: string; media: CallMediaKind }
+  | { t: "offer"; callId: string; sdp: string; media?: CallMediaKind }
+  | { t: "answer"; callId: string; sdp: string }
+  | { t: "candidates"; callId: string; candidates: CallIceCandidate[] }
+  | { t: "peer-accepted"; callId: string }
+  | { t: "peer-rejected"; callId: string; reason?: string }
+  | { t: "peer-hangup"; callId: string; reason?: string }
+  | {
+      t: "ice-servers";
+      callId: string;
+      iceServers: IceServerConfig[];
+      sfuFocus?: SfuFocus | null;
+    }
+  | { t: "call-state"; callId: string; state: CallState }
+  | { t: "pong" }
+  | { t: "error"; code: string; message?: string };
+
+// ---------------------------------------------------------------------------
+// REST contract (start call / mint ICE / call history)
+// ---------------------------------------------------------------------------
+
+export interface StartCallRequest {
+  to: string;
+  media: CallMediaKind;
+}
+
+export interface StartCallResponse {
+  callId: string;
+  iceServers: IceServerConfig[];
+  sfuFocus?: SfuFocus | null;
+}
+
+export interface IceServersResponse {
+  iceServers: IceServerConfig[];
+}
+
+export interface CallSessionSummary {
+  id: string;
+  peer: string;
+  direction: CallDirection;
+  state: CallState;
+  media: CallMediaKind;
+  createdAt: string;
+  connectedAt?: string | null;
+  endedAt?: string | null;
+  endReason?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime validation (used by the backend ingest to reject malformed frames)
+// ---------------------------------------------------------------------------
+
+const SIGNAL_TYPES: readonly RtcSignalType[] = [
+  "offer",
+  "answer",
+  "candidate",
+  "accept",
+  "reject",
+  "hangup",
+  "cancel",
+];
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isCallMediaKind(value: unknown): value is CallMediaKind {
+  return (
+    isPlainObject(value) &&
+    typeof value.audio === "boolean" &&
+    typeof value.video === "boolean"
+  );
+}
+
+function parseCandidates(value: unknown): CallIceCandidate[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) return undefined;
+  const out: CallIceCandidate[] = [];
+  for (const raw of value) {
+    if (!isPlainObject(raw) || typeof raw.candidate !== "string") continue;
+    out.push({
+      candidate: raw.candidate,
+      sdpMid: typeof raw.sdpMid === "string" ? raw.sdpMid : null,
+      sdpMLineIndex:
+        typeof raw.sdpMLineIndex === "number" ? raw.sdpMLineIndex : null,
+      usernameFragment:
+        typeof raw.usernameFragment === "string" ? raw.usernameFragment : null,
+    });
+  }
+  return out;
+}
+
+function parseSfuFocus(value: unknown): SfuFocus | null | undefined {
+  if (value === undefined) return undefined;
+  if (value === null) return null;
+  if (!isPlainObject(value)) return undefined;
+  if (typeof value.kind !== "string" || typeof value.url !== "string") {
+    return undefined;
+  }
+  return {
+    kind: value.kind,
+    url: value.url,
+    token: typeof value.token === "string" ? value.token : undefined,
+    room: typeof value.room === "string" ? value.room : undefined,
+  };
+}
+
+/**
+ * Parse + validate an inbound cross-instance signaling envelope. Returns the
+ * normalized envelope or `null` when the shape is invalid. Callers additionally
+ * enforce that the HTTP-Signature signer equals `from` and that the recipient
+ * (`to`) is a local actor.
+ */
+export function parseRtcSignalEnvelope(
+  input: unknown,
+): RtcSignalEnvelopeV1 | null {
+  if (!isPlainObject(input)) return null;
+  if (input.v !== RTC_SIGNAL_ENVELOPE_VERSION) return null;
+  const { callId, from, to, type, ts, ttlMs } = input;
+  if (
+    typeof callId !== "string" ||
+    callId.length === 0 ||
+    callId.length > 200 ||
+    typeof from !== "string" ||
+    from.length === 0 ||
+    typeof to !== "string" ||
+    to.length === 0 ||
+    typeof type !== "string" ||
+    !SIGNAL_TYPES.includes(type as RtcSignalType) ||
+    typeof ts !== "number" ||
+    !Number.isFinite(ts) ||
+    typeof ttlMs !== "number" ||
+    !Number.isFinite(ttlMs) ||
+    ttlMs < 0
+  ) {
+    return null;
+  }
+  const sdp = typeof input.sdp === "string" ? input.sdp : undefined;
+  // Guard against absurd SDP blobs abusing the endpoint as a relay.
+  if (sdp !== undefined && sdp.length > 100_000) return null;
+  return {
+    v: RTC_SIGNAL_ENVELOPE_VERSION,
+    callId,
+    from,
+    to,
+    type: type as RtcSignalType,
+    media: isCallMediaKind(input.media) ? input.media : undefined,
+    sdp,
+    candidates: parseCandidates(input.candidates),
+    sfuFocus: parseSfuFocus(input.sfuFocus),
+    reason:
+      typeof input.reason === "string"
+        ? input.reason.slice(0, 200)
+        : undefined,
+    ts,
+    ttlMs,
+  };
+}
+
+/** True when the envelope is still within its freshness window. */
+export function isEnvelopeFresh(
+  envelope: RtcSignalEnvelopeV1,
+  now: number,
+): boolean {
+  // Reject frames from the future (clock skew tolerance) or past their TTL.
+  const skewToleranceMs = 30_000;
+  if (envelope.ts - now > skewToleranceMs) return false;
+  return now - envelope.ts <= envelope.ttlMs;
+}

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

@@ -1,3 +1,6 @@
+// Call signaling wire contract + browser<->hub frames (voice + video).
+export * from "./call.ts";
+
 // ===== Yurucommu AP-Native Types =====
 
 // Actor represents a user (Person) in ActivityPub
@@ -122,14 +125,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

@@ -29,6 +29,7 @@ import { moderationRoutes } from "./routes/moderation.ts";
 import { appsApiRoutes, appsServeRoutes } from "./routes/apps.ts";
 import mobileRoutes from "./routes/mobile.ts";
 import notificationPusherRoutes from "./routes/notification-pushers.ts";
+import rtcRoutes from "./routes/rtc/index.ts";
 
 import { rateLimit, RateLimitConfigs } from "./middleware/rate-limit.ts";
 import { csrfProtection } from "./middleware/csrf.ts";
@@ -219,6 +220,7 @@ function buildSocialServerDiscovery(
   appUrl: string,
   issuer: string,
   options: YurucommuBackendDiscoveryOptionsV1 = {},
+  auth: { oidcClientId?: string; passwordEnabled?: boolean } = {},
 ) {
   const discovery = {
     ...DEFAULT_DISCOVERY_OPTIONS,
@@ -238,6 +240,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 +253,9 @@ function buildSocialServerDiscovery(
     endpoints: {
       api: `${appUrl}/api`,
       authProviders: `${appUrl}/api/auth/providers`,
+      mobilePasswordLogin: `${appUrl}/api/auth/mobile/login`,
+      mobileOidcExchange: `${appUrl}/api/auth/mobile/oidc`,
+      mobileLogout: `${appUrl}/api/auth/logout`,
       currentUser: `${appUrl}/api/auth/me`,
       timeline: `${appUrl}/api/timeline`,
       conversations: `${appUrl}/api/dm/contacts`,
@@ -331,9 +341,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);
@@ -488,6 +508,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
   app.use("*", async (c, next) => {
     await next();
 
+    // A 101 Switching Protocols response carries a WebSocket and immutable
+    // headers (the /api/rtc/socket call upgrade). Mutating it throws and breaks
+    // the upgrade, so skip the security-header pass for it.
+    if (c.res.status === 101) return;
+
     const preserveRouteSecurityHeaders = c.req.path.startsWith("/hosted/");
     const setSecurityHeader = (name: string, value: string) => {
       if (preserveRouteSecurityHeaders && c.res.headers.has(name)) {
@@ -535,9 +560,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
     setSecurityHeader("X-Content-Type-Options", "nosniff");
     setSecurityHeader("X-Frame-Options", "DENY");
     setSecurityHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+    // Allow the app's OWN origin to use camera + microphone (WebRTC calls);
+    // still deny geolocation and deny camera/mic to any cross-origin frame.
     setSecurityHeader(
       "Permissions-Policy",
-      "camera=(), microphone=(), geolocation=()",
+      "camera=(self), microphone=(self), geolocation=()",
     );
     // HSTS: once a client has reached this host over HTTPS, keep it on HTTPS
     // (defeats SSL-strip / downgrade). Sent unconditionally — browsers ignore it
@@ -564,14 +591,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;
     }
   });
 
@@ -658,6 +702,11 @@ function applyGlobalMiddleware(app: YurucommuApp): void {
     app.use(pattern, rateLimit(RateLimitConfigs.inbox));
   }
 
+  // Cross-instance call signaling ingest is unauthenticated at the network edge
+  // (it verifies an HTTP Signature inside the handler) and can be hit by any
+  // remote instance, so throttle it per-IP like the other federation endpoints.
+  app.use("/ap/rtc/signal", rateLimit(RateLimitConfigs.federationDiscovery));
+
   // Federation discovery endpoints are unauthenticated and can be probed by
   // any remote actor. Throttle them per-IP to mitigate enumeration / DoS.
   app.use(
@@ -731,6 +780,8 @@ function mountCoreRoutes(app: YurucommuApp): void {
   app.route("/api/moderation", moderationRoutes);
   app.route("/api/apps", appsApiRoutes);
   app.route("/hosted", appsServeRoutes);
+  // Call feature: /api/rtc/* (session) + /ap/rtc/signal (server-to-server).
+  app.route("/", rtcRoutes);
   app.route("/", activitypubRoutes);
 }
 
@@ -898,6 +949,10 @@ type WorkerBindings = EnvVars & {
   ASSETS?: Fetcher;
   DELIVERY_QUEUE?: Queue<DeliveryQueueMessageV1>;
   DELIVERY_DLQ?: Queue<DeliveryDlqMessageV1>;
+  // Signaling hub Durable Object namespace (call feature). wrapCloudflareBindings
+  // spreads it through untouched (it is not DB/MEDIA/KV/ASSETS) so app code and
+  // the rtc routes read it as c.env.CALL_SIGNALING.
+  CALL_SIGNALING?: DurableObjectNamespace;
 };
 
 export default {

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 });
+}