@hogsend/engine 0.6.0 → 0.8.0

package/src/lib/email-service-types.ts

@@ -53,6 +53,12 @@ export interface SendTrackedEmailOptions<
   replyTo?: string | string[];
   skipPreferenceCheck?: boolean;
   baseUrl?: string;
+  /**
+   * Caller-supplied idempotency key (POST /v1/emails). A retry with the same key
+   * short-circuits to the prior `email_sends` row instead of dispatching a
+   * duplicate provider send.
+   */
+  idempotencyKey?: string;
 }
 
 export interface TrackedSendResult {
@@ -128,6 +134,8 @@ export interface EmailServiceSendOptions<
   headers?: Record<string, string>;
   replyTo?: string | string[];
   skipPreferenceCheck?: boolean;
+  /** Caller-supplied idempotency key (POST /v1/emails) — dedups duplicate sends. */
+  idempotencyKey?: string;
 }
 
 export interface EmailServiceWebhookOptions {

package/src/lib/ingestion.ts

@@ -4,15 +4,27 @@ import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, journeyStates, userEvents } from "@hogsend/db";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 import { checkBucketMembership } from "../buckets/check-membership.js";
-import { upsertContact } from "./contacts.js";
+import { resolveOrCreateContact } from "./contacts.js";
 import type { Logger } from "./logger.js";
 
 export interface IngestEvent {
   event: string;
-  userId: string;
-  userEmail: string;
-  properties: Record<string, unknown>;
+  /** D1: optional — email-only / anonymous events resolve a key downstream. */
+  userId?: string;
+  userEmail?: string;
+  /** D1: future anonymous→identified path. Threaded into the resolver. */
+  anonymousId?: string;
+  /** D2: → `user_events` + Hatchet `trigger.where`/`exitOn` ONLY. */
+  eventProperties: Record<string, unknown>;
+  /** D2: → `contacts.properties` merge ONLY. */
+  contactProperties?: Record<string, unknown>;
   idempotencyKey?: string;
+  /**
+   * Caller-supplied event time (§2.5 `timestamp`). When set, `user_events`
+   * `occurred_at` is stamped from it (backfill/replay) instead of defaulting to
+   * the ingest instant. Accepts a `Date` or an ISO-8601 string.
+   */
+  occurredAt?: Date | string;
 }
 
 export interface ExitResult {
@@ -35,14 +47,36 @@ export async function ingestEvent(opts: {
 }): Promise<IngestResult> {
   const { db, registry, hatchet, logger, event } = opts;
 
+  // (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
+  // contact-referencing tables join on a NOT NULL text key, so an email-only /
+  // anonymous event (D1 optional userId) needs a canonical key resolved before
+  // any insert (risk 2). The resolver applies ONLY contactProperties to
+  // `contacts.properties` (D2 split) and returns BOTH the canonical contact id
+  // AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
+  // risk 1/6), so no second read-back of the contact row is needed.
+  const { resolvedKey } = await resolveOrCreateContact({
+    db,
+    userId: event.userId,
+    email: event.userEmail || undefined,
+    anonymousId: event.anonymousId,
+    contactProperties: event.contactProperties,
+  });
+
+  // Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
+  // falls back to the `occurred_at` DB default (ingest instant).
+  const occurredAt = event.occurredAt ? new Date(event.occurredAt) : undefined;
+
+  // (2) Idempotency dedup + `user_events` insert keyed on the resolved key, with
+  // ONLY eventProperties in the properties bag (D2).
   if (event.idempotencyKey) {
     const result = await db
       .insert(userEvents)
       .values({
-        userId: event.userId,
+        userId: resolvedKey,
         event: event.event,
-        properties: event.properties,
+        properties: event.eventProperties,
         idempotencyKey: event.idempotencyKey,
+        ...(occurredAt ? { occurredAt } : {}),
       })
       .onConflictDoNothing({
         target: userEvents.idempotencyKey,
@@ -54,14 +88,17 @@ export async function ingestEvent(opts: {
     }
   } else {
     await db.insert(userEvents).values({
-      userId: event.userId,
+      userId: resolvedKey,
       event: event.event,
-      properties: event.properties,
+      properties: event.eventProperties,
+      ...(occurredAt ? { occurredAt } : {}),
     });
   }
 
+  // (3) Build the JSON-serializable subset of eventProperties for the Hatchet
+  // push payload (scalars only — the SDK serializes the envelope).
   const serializableProperties = Object.fromEntries(
-    Object.entries(event.properties).filter(
+    Object.entries(event.eventProperties).filter(
       ([, v]) =>
         typeof v === "string" ||
         typeof v === "number" ||
@@ -70,57 +107,50 @@ export async function ingestEvent(opts: {
     ),
   ) as Record<string, string | number | boolean | null>;
 
+  // (4) Hatchet push + (5) checkExits, both keyed on the resolved key. The push
+  // payload wire key STAYS `properties` (bucket tests assert on it — risk 9).
   const [, exits] = await Promise.all([
     hatchet.events.push(event.event, {
-      userId: event.userId,
-      userEmail: event.userEmail,
+      userId: resolvedKey,
+      userEmail: event.userEmail ?? "",
       properties: serializableProperties,
     }),
     checkExits(db, registry, hatchet, logger, {
-      userId: event.userId,
+      userId: resolvedKey,
       eventName: event.event,
-      properties: event.properties,
-    }),
-    upsertContact({
-      db,
-      externalId: event.userId,
-      email: event.userEmail || undefined,
-      properties: event.properties,
-    }).catch((err) => {
-      logger.warn("Contact upsert failed", {
-        userId: event.userId,
-        error: err instanceof Error ? err.message : String(err),
-      });
+      properties: event.eventProperties,
     }),
   ]);
 
-  // Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
-  // Promise.all above: its property eval reads MERGED contact state, and its
-  // bucket:entered/left emissions recurse back into ingestEvent (the recursion
-  // guard in checkBucketMembership bounds them). Best-effort: a bucket failure
-  // must not fail the ingest of the originating event.
+  // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
+  // Promise.all above: its property eval reads contact state ⊕ this-ingest
+  // contactProperties patch, and its bucket:entered/left emissions recurse back
+  // into ingestEvent (the recursion guard in checkBucketMembership bounds them).
+  // Best-effort: a bucket failure must not fail the ingest of the originating
+  // event.
   try {
     await checkBucketMembership({
       db,
       registry,
       hatchet,
       logger,
-      userId: event.userId,
+      userId: resolvedKey,
       userEmail: event.userEmail || null,
       event: event.event,
-      properties: event.properties,
+      eventProperties: event.eventProperties,
+      contactProperties: event.contactProperties ?? {},
     });
   } catch (err) {
     logger.warn("Bucket membership check failed", {
       event: event.event,
-      userId: event.userId,
+      userId: resolvedKey,
       error: err instanceof Error ? err.message : String(err),
     });
   }
 
   logger.info("Event ingested", {
     event: event.event,
-    userId: event.userId,
+    userId: resolvedKey,
     exits: exits.filter((e) => e.exited).length,
   });
 

package/src/lib/mailer.ts

@@ -24,8 +24,17 @@ import type {
   SendResult,
   TrackedSendResult,
 } from "./email-service-types.js";
+import { hatchet } from "./hatchet.js";
+import { createLogger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
 import type { PrepareTrackedHtmlFn } from "./tracked.js";
 import { sendTrackedEmail } from "./tracked.js";
+import { resolveEmailSendContextByResendId } from "./tracking-events.js";
+
+// Fallback logger for the provider-webhook outbound emit — `config.logger` is
+// optional, but `emitOutbound` requires one. Mirrors the engine-lib singleton
+// pattern (define-journey, preferences, tracked).
+const emitLogger = createLogger(process.env.LOG_LEVEL);
 
 const WEBHOOK_TO_STATUS_FIELD: Partial<
   Record<WebhookEventType, keyof typeof emailSends.$inferSelect>
@@ -98,6 +107,7 @@ export function createTrackedMailer(
             headers: options.headers,
             replyTo: options.replyTo,
             skipPreferenceCheck: options.skipPreferenceCheck,
+            idempotencyKey: options.idempotencyKey,
             baseUrl: config.baseUrl,
           },
         });
@@ -186,9 +196,23 @@ export function createTrackedMailer(
   ): Promise<boolean> {
     switch (event.type) {
       case "email.sent":
+        // `email.sent` is emitted FIRST-PARTY from the tracked mailer's
+        // provider-accepted branch (lib/tracked.ts) with the rich payload — the
+        // provider-webhook echo only updates the DB status, it does NOT emit.
+        await updateEmailStatus(event.type, event.data.email_id);
+        break;
       case "email.delivered":
+        await updateEmailStatus(event.type, event.data.email_id);
+        // OUTBOUND `email.delivered` — the provider webhook is the SINGLE source
+        // for delivered/bounced (these have no first-party signal).
+        await emitProviderEmailEvent("email.delivered", event.data.email_id);
+        break;
       case "email.opened":
       case "email.clicked":
+        // First-party pixel/redirect is the SINGLE outbound emitter for
+        // open/click (gated on the first-touch null→set UPDATE in the tracking
+        // routes — risk 4). The provider-webhook echo is SUPPRESSED here: it only
+        // updates the DB status, it does NOT emit outbound (no double-source).
         await updateEmailStatus(event.type, event.data.email_id);
         break;
       case "email.bounced":
@@ -196,6 +220,11 @@ export function createTrackedMailer(
           bounceType: event.data.bounce?.type,
           bounceReason: event.data.bounce?.message,
         });
+        // OUTBOUND `email.bounced` with the bounce detail.
+        await emitProviderEmailEvent("email.bounced", event.data.email_id, {
+          bounceType: event.data.bounce?.type,
+          bounceReason: event.data.bounce?.message,
+        });
         await handleBounce(event.data.to);
         break;
       case "email.complained":
@@ -249,6 +278,65 @@ export function createTrackedMailer(
       .where(eq(emailPreferences.email, email));
   }
 
+  /**
+   * Emit the provider-funnel outbound event (`email.delivered` / `email.bounced`)
+   * for a Resend `email_id`. Enriches via {@link resolveEmailSendContextByResendId}
+   * (the only handle a provider webhook holds is the Resend id). Fire-and-forget:
+   * a missing context (webhook racing the send-row commit) or a transient outbound
+   * error is logged and swallowed — never failing the webhook handler. No
+   * `dedupeKey`: the provider path is not a Hatchet-retryable producer, and the
+   * shared `Webhook-Id` is the subscriber-side dedup for any provider redelivery.
+   */
+  function emitProviderEmailEvent(
+    event: "email.delivered" | "email.bounced",
+    resendId: string,
+    bounce?: { bounceType?: string; bounceReason?: string },
+  ): void {
+    if (!db) return;
+    const log = config.logger ?? emitLogger;
+    const database = db;
+    void resolveEmailSendContextByResendId(database, resendId)
+      .then((ctx) => {
+        if (!ctx) return;
+        const base = {
+          emailSendId: ctx.emailSendId,
+          resendId,
+          templateKey: ctx.templateKey,
+          userId: ctx.userId,
+          to: ctx.to,
+          at: new Date().toISOString(),
+        };
+        if (event === "email.bounced") {
+          return emitOutbound({
+            db: database,
+            hatchet,
+            logger: log,
+            event: "email.bounced",
+            payload: {
+              ...base,
+              ...(bounce?.bounceType ? { bounceType: bounce.bounceType } : {}),
+              ...(bounce?.bounceReason
+                ? { bounceReason: bounce.bounceReason }
+                : {}),
+            },
+          });
+        }
+        return emitOutbound({
+          db: database,
+          hatchet,
+          logger: log,
+          event: "email.delivered",
+          payload: base,
+        });
+      })
+      .catch((err: unknown) => {
+        log.warn(`emitOutbound ${event} failed`, {
+          resendId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+  }
+
   async function updateEmailStatus(
     eventType: WebhookEventType,
     resendId: string,

package/src/lib/outbound.ts

@@ -0,0 +1,216 @@
+import { randomUUID } from "node:crypto";
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import {
+  type Database,
+  webhookDeliveries,
+  webhookEndpoints,
+} from "@hogsend/db";
+import { and, eq, isNull, sql } from "drizzle-orm";
+import { deliverWebhookTask } from "../workflows/deliver-webhook.js";
+import type { SerializedContact } from "./contacts.js";
+import type { Logger } from "./logger.js";
+import {
+  WEBHOOK_EVENT_TYPES,
+  type WebhookEventType,
+} from "./webhook-signing.js";
+
+export {
+  type ResendEmailSendContext,
+  resolveEmailSendContextByResendId,
+} from "./tracking-events.js";
+
+/**
+ * The outbound event catalog re-exported for the emit spine. Identical to the
+ * signing lib's {@link WEBHOOK_EVENT_TYPES} — the single source of truth.
+ */
+export const OUTBOUND_EVENTS = WEBHOOK_EVENT_TYPES;
+export type OutboundEventName = WebhookEventType;
+
+interface EmailEventPayload {
+  emailSendId: string;
+  resendId: string | null;
+  templateKey: string | null;
+  userId: string | null;
+  to: string;
+  at: string;
+}
+
+interface BucketEventPayload {
+  bucketId: string;
+  bucketName: string;
+  userId: string;
+  userEmail: string | null;
+  transition: "entered" | "left";
+  entryCount: number;
+  source: string;
+}
+
+/**
+ * The typed per-event payload map. `data` in each delivered envelope is exactly
+ * `OutboundPayloads[E]` for the emitted event `E`. Producers (the 12 hook
+ * points) construct these; subscribers receive them under `envelope.data`.
+ */
+export interface OutboundPayloads {
+  "contact.created": SerializedContact;
+  "contact.updated": SerializedContact;
+  "contact.deleted": {
+    id: string;
+    externalId: string | null;
+    email: string | null;
+  };
+  "contact.unsubscribed": {
+    externalId: string | null;
+    email: string | null;
+    category: string | null;
+    scope: "all" | "category";
+  };
+  "email.sent": {
+    emailSendId: string;
+    resendId: string;
+    templateKey: string | null;
+    to: string;
+    userId: string | null;
+    category: string | null;
+    journeyStateId: string | null;
+    subject: string;
+    sentAt: string;
+  };
+  "email.delivered": EmailEventPayload;
+  "email.opened": EmailEventPayload;
+  "email.clicked": EmailEventPayload & { linkUrl?: string; linkId?: string };
+  "email.bounced": EmailEventPayload & {
+    bounceType?: string;
+    bounceReason?: string;
+  };
+  "journey.completed": {
+    journeyId: string;
+    journeyName: string;
+    stateId: string;
+    userId: string;
+    userEmail: string;
+    completedAt: string;
+  };
+  "bucket.entered": BucketEventPayload;
+  "bucket.left": BucketEventPayload & { reason?: string };
+}
+
+/**
+ * The signed envelope shape written to `webhook_deliveries.payload` and sent
+ * verbatim to subscribers. `id` is the shared `Webhook-Id`; `timestamp` is the
+ * logical-event time (ISO); `data` is the typed per-event payload.
+ */
+interface OutboundEnvelope<E extends OutboundEventName> {
+  id: string;
+  type: E;
+  timestamp: string;
+  data: OutboundPayloads[E];
+}
+
+/**
+ * THE fire-and-forget emit spine. It does NOT deliver — it selects the active,
+ * subscribed endpoints for `event`, inserts one `webhook_deliveries` row per
+ * endpoint (all sharing ONE `webhookId` = the `Webhook-Id` header), and enqueues
+ * the durable {@link deliverWebhookTask} per inserted row.
+ *
+ * Idempotency: when `dedupeKey` is provided, the unique
+ * `(endpointId, dedupeKey)` index makes a re-emit (e.g. a Hatchet retry of the
+ * producing task) a no-op via `onConflictDoNothing` — no duplicate row, no
+ * second enqueue. Events without a `dedupeKey` are never deduped (NULL keys are
+ * distinct in Postgres), which is correct for non-retryable emit points.
+ *
+ * NEVER throws to callers. Internal failures (endpoint select, insert, enqueue)
+ * are logged via `logger.warn` and swallowed so a transient outbound error can
+ * never fail a contact upsert / email send / journey step. Callers MUST STILL
+ * wrap the call as `void emitOutbound(...).catch(logger.warn)` — the `.catch` is
+ * defence-in-depth against a programming error that escapes this guard.
+ *
+ * Single-tenant: only endpoints with `organizationId IS NULL` are selected and
+ * the delivery rows are written with `organizationId ?? null`. Multi-tenant
+ * scoping is a later non-breaking change.
+ */
+export async function emitOutbound<E extends OutboundEventName>(opts: {
+  db: Database;
+  hatchet: HatchetClient;
+  logger: Logger;
+  event: E;
+  payload: OutboundPayloads[E];
+  dedupeKey?: string;
+  organizationId?: string | null;
+}): Promise<void> {
+  const { db, logger, event, payload, dedupeKey } = opts;
+  const organizationId = opts.organizationId ?? null;
+
+  try {
+    const webhookId = `msg_${randomUUID()}`;
+    const timestamp = new Date();
+
+    // (2) Active, subscribed endpoints. `event_types @> '["<event>"]'` matches
+    // the jsonb array containing this event. Single-tenant: organizationId IS
+    // NULL (NOT a hardcoded tenant — keeps the MT wiring non-breaking).
+    const endpoints = await db
+      .select({ id: webhookEndpoints.id })
+      .from(webhookEndpoints)
+      .where(
+        and(
+          eq(webhookEndpoints.disabled, false),
+          isNull(webhookEndpoints.organizationId),
+          sql`${webhookEndpoints.eventTypes} @> ${JSON.stringify([event])}::jsonb`,
+        ),
+      );
+
+    if (endpoints.length === 0) return;
+
+    // (3) The frozen envelope — signed + sent verbatim by the delivery task.
+    const envelope: OutboundEnvelope<E> = {
+      id: webhookId,
+      type: event,
+      timestamp: timestamp.toISOString(),
+      data: payload,
+    };
+
+    // (4) One delivery row per endpoint, sharing the webhookId. onConflictDoNothing
+    // on (endpointId, dedupeKey) is the producer-side fan-out idempotency guard.
+    const inserted = await db
+      .insert(webhookDeliveries)
+      .values(
+        endpoints.map((endpoint) => ({
+          endpointId: endpoint.id,
+          organizationId,
+          webhookId,
+          eventType: event,
+          dedupeKey: dedupeKey ?? null,
+          payload: envelope as unknown as Record<string, unknown>,
+          status: "pending" as const,
+          attemptCount: 0,
+          nextRetryAt: timestamp,
+        })),
+      )
+      .onConflictDoNothing({
+        target: [webhookDeliveries.endpointId, webhookDeliveries.dedupeKey],
+      })
+      .returning({ id: webhookDeliveries.id });
+
+    // (5) Enqueue the durable delivery task per freshly-inserted row,
+    // fire-and-forget. A failed enqueue is recovered by the reaper (the row is
+    // already `pending` with `nextRetryAt <= now`), so a broker hiccup here only
+    // delays — never drops — a delivery.
+    for (const row of inserted) {
+      void deliverWebhookTask
+        .runNoWait({ deliveryId: row.id })
+        .catch((error: unknown) => {
+          logger.warn("emitOutbound: deliverWebhookTask enqueue failed", {
+            deliveryId: row.id,
+            event,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+    }
+  } catch (error) {
+    // FAIL-SAFE: never propagate an outbound error onto the producer's hot path.
+    logger.warn("emitOutbound failed", {
+      event,
+      dedupeKey,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/src/lib/preferences.ts

@@ -0,0 +1,137 @@
+import type { Database } from "@hogsend/db";
+import { emailPreferences } from "@hogsend/db";
+import { sql } from "drizzle-orm";
+import { resolveRecipient } from "./contacts.js";
+import { hatchet } from "./hatchet.js";
+import { createLogger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
+
+const logger = createLogger(process.env.LOG_LEVEL);
+
+/**
+ * Single source of truth for an `email_preferences` upsert: the `(user_id, email)`
+ * onConflict + the jsonb category-flip. Extracted from the private
+ * `upsertPreference` that used to live in `routes/email/unsubscribe.ts` (decision
+ * #9) so subscribe/unsubscribe routes, the preference center, list membership, and
+ * the unsubscribe-token flow all share ONE write.
+ *
+ * `externalId` is the `user_id` column value: the contact's `external_id` when it
+ * has one, else the contact `id` (uuid) fallback for an email-only contact (risk
+ * 10). `email` is REQUIRED — both columns are NOT NULL and form the PK.
+ */
+export async function upsertEmailPreference(opts: {
+  db: Database;
+  externalId: string;
+  email: string;
+  update: {
+    unsubscribedAll?: boolean;
+    suppressed?: boolean;
+    categoryKey?: string;
+    categoryValue?: boolean;
+  };
+}): Promise<void> {
+  const { db, externalId, email, update } = opts;
+
+  const setClause: Record<string, unknown> = { updatedAt: new Date() };
+
+  if (update.unsubscribedAll !== undefined) {
+    setClause.unsubscribedAll = update.unsubscribedAll;
+  }
+  if (update.suppressed !== undefined) {
+    setClause.suppressed = update.suppressed;
+  }
+  if (update.categoryKey !== undefined) {
+    const jsonValue = update.categoryValue ? "true" : "false";
+    setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
+  }
+
+  await db
+    .insert(emailPreferences)
+    .values({
+      userId: externalId,
+      email,
+      ...(update.unsubscribedAll !== undefined
+        ? { unsubscribedAll: update.unsubscribedAll }
+        : {}),
+      ...(update.suppressed !== undefined
+        ? { suppressed: update.suppressed }
+        : {}),
+      ...(update.categoryKey !== undefined
+        ? {
+            categories: { [update.categoryKey]: update.categoryValue ?? false },
+          }
+        : {}),
+    })
+    .onConflictDoUpdate({
+      target: [emailPreferences.userId, emailPreferences.email],
+      set: setClause,
+    });
+
+  // OUTBOUND `contact.unsubscribed` — this is the SINGLE choke for ALL preference
+  // writes (token unsub, preference center, list-membership flips), so the emit
+  // lives here once. GATED to a genuine opt-OUT only: a full unsubscribe
+  // (`unsubscribedAll === true`) or a category flip to false. A resubscribe
+  // (`unsubscribedAll === false` / `categoryValue === true`) does NOT emit. Uses
+  // the engine `hatchet`/`logger` singletons (this lib has no request container);
+  // fire-and-forget so a transient outbound error never fails the pref write.
+  const isUnsubscribe =
+    update.unsubscribedAll === true || update.categoryValue === false;
+  if (isUnsubscribe) {
+    const scope: "all" | "category" =
+      update.unsubscribedAll === true ? "all" : "category";
+    void emitOutbound({
+      db,
+      hatchet,
+      logger,
+      event: "contact.unsubscribed",
+      payload: {
+        externalId,
+        email,
+        category: update.categoryKey ?? null,
+        scope,
+      },
+    }).catch(logger.warn);
+  }
+}
+
+/**
+ * D3 list-membership write. Resolves the caller's identity to the deterministic
+ * `(externalId | contactId fallback, email)` pair via `resolveRecipient`, then
+ * writes one category flip per list key through `upsertEmailPreference`.
+ *
+ * Requires a resolvable email — `email_preferences.email` is NOT NULL and the
+ * preference center / unsubscribe-token flow key on it (risk 10). The caller is
+ * expected to have already run `resolveOrCreateContact` (so the contact exists);
+ * this reads identity back. Throws if no email can be resolved — the route maps
+ * that to a 400 ("Contact has no email; cannot manage list membership").
+ */
+export async function applyListMembership(opts: {
+  db: Database;
+  userId?: string;
+  email?: string;
+  lists: Record<string, boolean>;
+}): Promise<void> {
+  const { db, userId, email, lists } = opts;
+
+  const entries = Object.entries(lists);
+  if (entries.length === 0) return;
+
+  const recipient = await resolveRecipient({ db, userId, email });
+  if (!recipient) {
+    throw new Error("Contact has no email; cannot manage list membership");
+  }
+
+  // `user_id` column = external_id when present, else the contact id (uuid)
+  // fallback — the SAME deterministic key used by subscribe writes,
+  // preference-center reads, and unsubscribe-token issuance (risk 10).
+  const externalId = recipient.externalId ?? recipient.contactId;
+
+  for (const [categoryKey, categoryValue] of entries) {
+    await upsertEmailPreference({
+      db,
+      externalId,
+      email: recipient.email,
+      update: { categoryKey, categoryValue },
+    });
+  }
+}