create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/waitlist-experiments.ts

@@ -0,0 +1,213 @@
+/**
+ * @file waitlist-experiments.ts
+ * @description The Prisma-touching glue for waitlist experiments (#4661 D5).
+ *
+ * Mirrors `flow-engine.ts`'s `upsertFlowDefinition` / `seedFlowPresets`
+ * shape exactly: `upsertWaitlistExperiment` is the ONLY write path into
+ * `waitlist_experiments` (validate → upsert, never a second Prisma write
+ * elsewhere), and `seedWaitlistExperiments` is the `seedFlowPresets` loop
+ * verbatim in shape (stop at first failure; report `seeded[]`).
+ *
+ * `materializeWaitlistFlows` (#4726) closes the gap `seedFlowPresets` never
+ * had to close: an experiment row alone leaves `GET /v1/flows/:slug`
+ * answering `flow_not_found` (`serveFlow`, `flow-engine.ts`) because nothing
+ * ever compiled + wrote the `flow_definitions` row the runtime reads. It
+ * composes `compileWaitlistFlow` (`@working-theory/validation`, pure) and
+ * `upsertFlowDefinition` (`flow-engine.ts`, the existing validated write
+ * path) — one `FlowConfig` per `config.waitlists[]` entry — never a second
+ * ad-hoc Prisma write. `seedWaitlistExperiments` calls it for every config
+ * right after that config's experiment row upserts, stopping the whole run
+ * at the first compile-or-write failure, exactly like every other failure
+ * this loop already stops on.
+ *
+ * PII boundary: only `{ siteId, key }` appear in logs — never `config`
+ * (mirrors flow-engine.ts's boundary).
+ */
+
+import type { Prisma } from "@working-theory/database";
+import {
+  compileWaitlistFlow,
+  waitlistExperimentConfigSchema,
+  type WaitlistExperimentConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import { upsertFlowDefinition } from "./flow-engine.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type WaitlistExperimentErrorKind =
+  | "invalid_input"
+  | "unknown_waitlist"
+  | "unsupported_by_engine"
+  | "flows_not_configured";
+
+export type WaitlistExperimentError = {
+  kind: WaitlistExperimentErrorKind;
+  message: string;
+};
+
+export type UpsertWaitlistExperimentResult =
+  | { ok: true; id: string }
+  | { ok: false; error: WaitlistExperimentError };
+
+export type SeedWaitlistExperimentsResult =
+  | { ok: true; seeded: string[] }
+  | { ok: false; error: WaitlistExperimentError; seeded: string[] };
+
+const WAITLIST_EXPERIMENT_ID_SELECT = {
+  id: true,
+} as const satisfies Prisma.WaitlistExperimentSelect;
+
+type WaitlistExperimentIdRow = Prisma.WaitlistExperimentGetPayload<{
+  select: typeof WAITLIST_EXPERIMENT_ID_SELECT;
+}>;
+
+// ─── upsertWaitlistExperiment — the ONLY write path (D5) ────────────────────
+
+/**
+ * Validate `raw` against `waitlistExperimentConfigSchema` and upsert it on
+ * `[siteId, key]`, writing `mode`/`status`/`config`. An invalid config never
+ * reaches Prisma.
+ */
+export async function upsertWaitlistExperiment(
+  siteId: string,
+  raw: unknown,
+): Promise<UpsertWaitlistExperimentResult> {
+  const parsed = waitlistExperimentConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: parsed.error.issues[0]?.message ?? "invalid experiment config",
+      },
+    };
+  }
+
+  const config: WaitlistExperimentConfig = parsed.data;
+
+  const row: WaitlistExperimentIdRow = await prisma.waitlistExperiment.upsert({
+    where: { siteId_key: { siteId, key: config.key } },
+    create: {
+      siteId,
+      key: config.key,
+      mode: config.mode,
+      status: config.status,
+      config: config as unknown as Prisma.InputJsonValue,
+    },
+    update: {
+      mode: config.mode,
+      status: config.status,
+      config: config as unknown as Prisma.InputJsonValue,
+    },
+    select: WAITLIST_EXPERIMENT_ID_SELECT,
+  });
+
+  return { ok: true, id: row.id };
+}
+
+// ─── materializeWaitlistFlows — compile+upsert one FlowDefinition per
+//     waitlists[] entry (#4726) ─────────────────────────────────────────────
+
+/**
+ * Compile every `raw.waitlists[]` entry into its `FlowConfig` via
+ * `compileWaitlistFlow` and upsert each through the existing validated
+ * `upsertFlowDefinition` path (`flow-engine.ts`) — never a second ad-hoc
+ * Prisma write. `raw` is (re-)validated against
+ * `waitlistExperimentConfigSchema` here — the same schema
+ * `upsertWaitlistExperiment` validates against — so this function is
+ * self-contained: an invalid config never reaches `compileWaitlistFlow`.
+ *
+ * Stops at the FIRST compile-or-write failure (mirrors
+ * `seedWaitlistExperiments`'s §D5 stop-at-first-failure discipline): a
+ * caller must not seed a partial, silently-broken flow set. The returned
+ * error's `message` always names the failing `waitlist.key`, and no
+ * `flow_definitions` row is written for that waitlist.
+ */
+export async function materializeWaitlistFlows(
+  siteId: string,
+  raw: unknown,
+): Promise<{ ok: true } | { ok: false; error: WaitlistExperimentError }> {
+  const parsed = waitlistExperimentConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        kind: "invalid_input",
+        message: parsed.error.issues[0]?.message ?? "invalid experiment config",
+      },
+    };
+  }
+  const config: WaitlistExperimentConfig = parsed.data;
+
+  for (const waitlist of config.waitlists) {
+    const compiled = compileWaitlistFlow(config, waitlist.key);
+    if (!compiled.ok) {
+      return {
+        ok: false,
+        error: {
+          kind: compiled.code,
+          message: `waitlist "${waitlist.key}": ${compiled.detail}`,
+        },
+      };
+    }
+
+    const upserted = await upsertFlowDefinition(siteId, compiled.flow);
+    if (!upserted.ok) {
+      return {
+        ok: false,
+        error: {
+          kind:
+            upserted.error.kind === "flows_not_configured"
+              ? "flows_not_configured"
+              : "invalid_input",
+          message: `waitlist "${waitlist.key}": ${upserted.error.message}`,
+        },
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+// ─── seedWaitlistExperiments (D5 — the seedFlowPresets loop verbatim) ───────
+
+/**
+ * Write the given experiment configs through the existing validated
+ * `upsertWaitlistExperiment` path, once per config, for the given site —
+ * then, for the same config, compile+upsert its `flow_definitions` rows via
+ * `materializeWaitlistFlows` (#4726), so a config is only ever recorded as
+ * `seeded` once BOTH its experiment row and every one of its waitlists'
+ * flow definitions have written successfully.
+ *
+ * Stops and returns the first `invalid_input` / `unknown_waitlist` /
+ * `unsupported_by_engine` / `flows_not_configured` failure rather than
+ * swallowing it (mirrors `seedFlowPresets`'s §3.3 discipline) — `seeded`
+ * names the experiment keys fully written before any failure.
+ */
+export async function seedWaitlistExperiments(
+  siteId: string,
+  configs: unknown[],
+): Promise<SeedWaitlistExperimentsResult> {
+  const seeded: string[] = [];
+  for (const config of configs) {
+    const result = await upsertWaitlistExperiment(siteId, config);
+    if (!result.ok) {
+      return { ok: false, error: result.error, seeded };
+    }
+
+    const flows = await materializeWaitlistFlows(siteId, config);
+    if (!flows.ok) {
+      return { ok: false, error: flows.error, seeded };
+    }
+
+    const key =
+      typeof config === "object" && config !== null && "key" in config
+        ? String((config as { key: unknown }).key)
+        : "(unknown)";
+    seeded.push(key);
+  }
+  return { ok: true, seeded };
+}

package/templates/apps/api/src/services/waitlist-followup.ts

@@ -0,0 +1,486 @@
+/**
+ * @file waitlist-followup.ts
+ * @description The waitlist follow-up-sequence sweep service (#4732 D1/D2/
+ * D3/D5).
+ *
+ * `runWaitlistFollowUpSweep` is the one entry point: for each `FlowDefinition`
+ * whose live `config` parses with a `followUps` block, and for each entry,
+ * select completed `FlowSession` rows past that entry's `offsetDays`, filter
+ * to leads whose `WaitlistScore.tier` matches the entry's `tiers[]`, drop any
+ * `(leadId, followUpKey)` pair already stamped on `waitlist_followup_sends`,
+ * apply the two suppression checks (a booked call, an unsubscribed Resend
+ * contact), and send the due remainder once each through the existing
+ * `sendAbandonEmail` — recording every attempted send (`sent` or `failed`) on
+ * `waitlist_followup_sends`. Invoked by the CLI entry
+ * (`src/bin/followup-sweep.ts`) on an operator-supplied cadence — this
+ * service is stateless and has no timer of its own (D1: no queue/cron
+ * infrastructure, mirrors `abandon-email.ts` #3962 D1 exactly).
+ *
+ * D5: the sweep reads the LIVE `FlowDefinition.config` on every run
+ * (`flowConfigSchema.safeParse`, exactly like `abandon-email.ts`'s
+ * `sweepAllDefinitions`) — never a per-session pinned `configSnapshot`. A
+ * stored config that has drifted from the schema is skip-and-logged, never
+ * silently stopping the sequence forever (the same lesson `abandon-email.ts`'s
+ * own code-review finding established).
+ *
+ * PII boundary: logs carry only `{ siteId, flowSlug, followUpKey, leadId,
+ * outcome }` — never email/copy values (mirrors abandon-email.ts's +
+ * deliverable-fulfillment.ts's boundary).
+ */
+
+import { getResendClient, sendAbandonEmail } from "@working-theory/email";
+import { logger } from "@working-theory/observability";
+import {
+  flowConfigSchema,
+  type FollowUpEntry,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type WaitlistFollowUpSweepSummary = {
+  scanned: number;
+  selected: number;
+  sent: number;
+  suppressed: number;
+  failed: number;
+  skipped: number;
+};
+
+export type WaitlistFollowUpSweepError = {
+  kind: "flows_not_configured" | "unexpected_error";
+  message: string;
+};
+
+export type WaitlistFollowUpSweepResult =
+  | { ok: true; summary: WaitlistFollowUpSweepSummary }
+  | { ok: false; error: WaitlistFollowUpSweepError };
+
+export type RunWaitlistFollowUpSweepOptions = {
+  siteId?: string;
+  now?: Date;
+};
+
+type FlowDefinitionRow = {
+  id: string;
+  siteId: string;
+  slug: string;
+  config: unknown;
+};
+
+type FollowUpCandidateRow = {
+  id: string;
+  siteId: string;
+  flowSlug: string;
+  leadId: string | null;
+  email: string | null;
+  locale: string | null;
+  completedAt: Date | null;
+};
+
+// ─── DB-required guard (mirrors abandon-email.ts's requireDb) ──────────────────
+
+const FLOWS_NOT_CONFIGURED_ERROR = {
+  kind: "flows_not_configured" as const,
+  message: "Flows are not configured.",
+};
+
+function requireDb(): WaitlistFollowUpSweepError | null {
+  if (!process.env.DATABASE_URL) return FLOWS_NOT_CONFIGURED_ERROR;
+  return null;
+}
+
+// ─── PII-safe outcome logging ───────────────────────────────────────────────────
+
+type FollowUpOutcome =
+  | "sent"
+  | "failed"
+  | "wrong_tier"
+  | "not_due"
+  | "callback_suppressed"
+  | "unsubscribed"
+  | "unsubscribe_check_failed"
+  | "sender_unconfigured";
+
+const OUTCOME_MESSAGE: Record<FollowUpOutcome, string> = {
+  sent: "[waitlist-followup] candidate selected — sent",
+  failed: "[waitlist-followup] candidate selected — send failed",
+  wrong_tier: "[waitlist-followup] candidate skipped — tier not in entry.tiers",
+  not_due: "[waitlist-followup] candidate skipped — offset not yet due",
+  callback_suppressed:
+    "[waitlist-followup] candidate skipped — booked-call suppression (Callback.payload.email match)",
+  unsubscribed:
+    "[waitlist-followup] candidate skipped — unsubscribed in Resend audience",
+  unsubscribe_check_failed:
+    "[waitlist-followup] candidate skipped (unstamped, retried next run) — Resend Contacts lookup failed",
+  sender_unconfigured:
+    "[waitlist-followup] candidate skipped (unstamped, retried next run) — no from-address configured",
+};
+
+function logOutcome(
+  candidate: { siteId: string; flowSlug: string; leadId: string | null },
+  followUpKey: string,
+  outcome: FollowUpOutcome,
+): void {
+  logger.info(
+    {
+      siteId: candidate.siteId,
+      flowSlug: candidate.flowSlug,
+      followUpKey,
+      leadId: candidate.leadId,
+      outcome,
+    },
+    OUTCOME_MESSAGE[outcome],
+  );
+}
+
+// ─── Copy resolution (mirrors abandon-email.ts's resolveCopy) ──────────────────
+
+function resolveCopy(
+  copy: Record<string, string>,
+  sessionLocale: string | null,
+  defaultLocale: string,
+): string {
+  const locale = sessionLocale ?? defaultLocale;
+  return copy[locale] ?? copy[defaultLocale] ?? "";
+}
+
+// ─── D2 — booked-call suppression (Callback.payload.email, best-effort) ────────
+
+type CallbackRow = { payload: unknown };
+
+/** Extracts `payload.email` from a `Callback` row, when the caller supplied one. */
+function callbackEmail(row: CallbackRow): string | undefined {
+  if (typeof row.payload !== "object" || row.payload === null) return undefined;
+  const email = (row.payload as Record<string, unknown>)["email"];
+  return typeof email === "string" ? email : undefined;
+}
+
+/**
+ * The set of lowercased emails with an open `Callback` row for `siteId` (D2)
+ * — fetched once per site per sweep run and cached across every
+ * `FlowDefinition`/entry for that site (D2's Escalation Boundary explicitly
+ * assumes low per-site volume; a `since`/`limit` window is a named,
+ * out-of-scope follow-up, never silently added here).
+ */
+async function loadCallbackEmails(siteId: string): Promise<Set<string>> {
+  const rows = (await prisma.callback.findMany({
+    where: { siteId },
+    select: { payload: true },
+  })) as CallbackRow[];
+  const emails = new Set<string>();
+  for (const row of rows) {
+    const email = callbackEmail(row);
+    if (email) emails.add(email.toLowerCase());
+  }
+  return emails;
+}
+
+// ─── D3 — unsubscribe suppression (optional RESEND_AUDIENCE_ID) ────────────────
+
+type UnsubscribeCheck =
+  | { ok: true; unsubscribed: boolean }
+  | { ok: false };
+
+/**
+ * Guarded BEFORE the API call (D3, AC-5): with `RESEND_AUDIENCE_ID` unset,
+ * this function is never invoked at all — see the caller. A `404`/not-found
+ * response means the contact isn't tracked in that audience (the expected
+ * common case today) and is treated as NOT unsubscribed; any other API error
+ * (network/auth/an undocumented SDK-shape surprise, §5.3) returns `ok:
+ * false` so the caller skips the send this run WITHOUT stamping — the next
+ * sweep retries.
+ */
+async function checkUnsubscribed(
+  email: string,
+  audienceId: string,
+): Promise<UnsubscribeCheck> {
+  try {
+    const { data, error } = await getResendClient().contacts.get({
+      email,
+      audienceId,
+    });
+    if (error) {
+      if (error.statusCode === 404) return { ok: true, unsubscribed: false };
+      return { ok: false };
+    }
+    return { ok: true, unsubscribed: data?.unsubscribed === true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// ─── The sweep ──────────────────────────────────────────────────────────────────
+
+/**
+ * The unguarded sweep body — mutates `summary` in place as it goes, so a
+ * mid-loop throw still leaves the caller's catch block able to log how far
+ * it got (mirrors abandon-email.ts's own posture).
+ */
+async function sweepAllDefinitions(
+  opts: RunWaitlistFollowUpSweepOptions,
+  now: Date,
+  fromAddress: string | undefined,
+  audienceId: string | undefined,
+  summary: WaitlistFollowUpSweepSummary,
+): Promise<void> {
+  const definitions = (await prisma.flowDefinition.findMany({
+    ...(opts.siteId !== undefined && { where: { siteId: opts.siteId } }),
+    select: { id: true, siteId: true, slug: true, config: true },
+  })) as FlowDefinitionRow[];
+
+  const callbackEmailsBySite = new Map<string, Set<string>>();
+  async function callbackEmailsFor(siteId: string): Promise<Set<string>> {
+    const cached = callbackEmailsBySite.get(siteId);
+    if (cached) return cached;
+    const emails = await loadCallbackEmails(siteId);
+    callbackEmailsBySite.set(siteId, emails);
+    return emails;
+  }
+
+  for (const definition of definitions) {
+    const parsedConfig = flowConfigSchema.safeParse(definition.config);
+    if (!parsedConfig.success) {
+      // Surface, do not swallow — mirrors abandon-email.ts's own posture: a
+      // stored config that has drifted from the schema must not silently
+      // stop this flow's follow-up sequence from ever running again with no
+      // operator-visible signal.
+      logger.warn(
+        {
+          siteId: definition.siteId,
+          flowSlug: definition.slug,
+          zodIssue: parsedConfig.error.issues[0]?.message,
+        },
+        "[waitlist-followup] skipping flow — stored config failed schema validation",
+      );
+      continue;
+    }
+    const config = parsedConfig.data;
+    const followUps = config.followUps;
+    // Block absent = follow-up sequence OFF for this flow — never selected.
+    if (!followUps) continue;
+
+    // Base completed-session candidate set — shared across every entry for
+    // this definition (each entry applies its own offset/tier filter below).
+    const candidates = (await prisma.flowSession.findMany({
+      where: {
+        flowId: definition.id,
+        completedAt: { not: null },
+        leadId: { not: null },
+        email: { not: null },
+      },
+      select: {
+        id: true,
+        siteId: true,
+        flowSlug: true,
+        leadId: true,
+        email: true,
+        locale: true,
+        completedAt: true,
+      },
+    })) as FollowUpCandidateRow[];
+
+    if (candidates.length === 0) continue;
+
+    const leadIds = [...new Set(candidates.map((c) => c.leadId as string))];
+
+    const scores = (await prisma.waitlistScore.findMany({
+      where: { leadId: { in: leadIds } },
+      select: { leadId: true, tier: true },
+    })) as { leadId: string; tier: string }[];
+    const tierByLead = new Map(scores.map((s) => [s.leadId, s.tier]));
+
+    const callbackEmails = await callbackEmailsFor(definition.siteId);
+
+    for (const entry of followUps) {
+      const alreadySent = (await prisma.waitlistFollowUpSend.findMany({
+        where: { followUpKey: entry.key, leadId: { in: leadIds } },
+        select: { leadId: true },
+      })) as { leadId: string }[];
+      const alreadySentLeads = new Set(alreadySent.map((s) => s.leadId));
+
+      for (const candidate of candidates) {
+        summary.scanned += 1;
+        const leadId = candidate.leadId as string;
+        const email = candidate.email as string;
+
+        if (alreadySentLeads.has(leadId)) continue; // idempotency (AC-3) — silent, not a "skip reason"
+
+        const tier = tierByLead.get(leadId);
+        if (!tier || !entry.tiers.includes(tier)) {
+          logOutcome(candidate, entry.key, "wrong_tier");
+          summary.skipped += 1;
+          continue;
+        }
+
+        const dueAt = addDays(candidate.completedAt as Date, entry.offsetDays);
+        if (dueAt > now) {
+          logOutcome(candidate, entry.key, "not_due");
+          summary.skipped += 1;
+          continue;
+        }
+
+        summary.selected += 1;
+
+        if (callbackEmails.has(email.toLowerCase())) {
+          logOutcome(candidate, entry.key, "callback_suppressed");
+          summary.suppressed += 1;
+          continue;
+        }
+
+        if (audienceId) {
+          const unsubCheck = await checkUnsubscribed(email, audienceId);
+          if (!unsubCheck.ok) {
+            // D3: leave the candidate UNSTAMPED — a network/auth/SDK-shape
+            // error must not be mistaken for "not unsubscribed."
+            logOutcome(candidate, entry.key, "unsubscribe_check_failed");
+            summary.skipped += 1;
+            continue;
+          }
+          if (unsubCheck.unsubscribed) {
+            logOutcome(candidate, entry.key, "unsubscribed");
+            summary.suppressed += 1;
+            continue;
+          }
+        }
+
+        if (!fromAddress) {
+          // An env gap must not consume the one send: leave the candidate
+          // UNSTAMPED so a later configured run still sends it (mirrors
+          // abandon-email.ts's D4 posture).
+          logOutcome(candidate, entry.key, "sender_unconfigured");
+          summary.skipped += 1;
+          continue;
+        }
+
+        const outcome = await sendAndStamp(
+          candidate,
+          entry,
+          email,
+          fromAddress,
+          config.defaultLocale,
+          now,
+        );
+        summary[outcome] += 1;
+      }
+    }
+  }
+}
+
+/** Resolve copy → build cta/resumeLink (D4) → send → stamp + log. */
+async function sendAndStamp(
+  candidate: FollowUpCandidateRow,
+  entry: FollowUpEntry,
+  email: string,
+  fromAddress: string,
+  defaultLocale: string,
+  now: Date,
+): Promise<"sent" | "failed"> {
+  const subject = resolveCopy(entry.copy.subject, candidate.locale, defaultLocale);
+  const body = resolveCopy(entry.copy.body, candidate.locale, defaultLocale);
+  const cta = entry.cta
+    ? resolveCopy(entry.cta.label, candidate.locale, defaultLocale)
+    : undefined;
+  // D4: followUps[].cta.label → cta, followUps[].cta.href → resumeLink,
+  // reusing AbandonEmailInput's existing generic shape unchanged.
+  const resumeLink = entry.cta?.href;
+
+  const sendResult = await sendAbandonEmail({
+    to: email,
+    fromAddress,
+    subject,
+    body,
+    ...(cta !== undefined && { cta }),
+    ...(resumeLink !== undefined && { resumeLink }),
+  });
+
+  const outcome: "sent" | "failed" = sendResult.ok ? "sent" : "failed";
+  try {
+    await prisma.waitlistFollowUpSend.create({
+      data: {
+        siteId: candidate.siteId,
+        leadId: candidate.leadId as string,
+        followUpKey: entry.key,
+        sentAt: now,
+        status: outcome,
+      },
+    });
+  } catch (err) {
+    // A `@@unique([leadId, followUpKey])` violation (P2002) here means a
+    // CONCURRENT overlapping sweep run already claimed/stamped this same
+    // pair between our idempotency read and this write — the check-then-act
+    // race the `abandon:sweep` doc-sync claim ("overlap … is harmless")
+    // assumes is closed by the constraint alone (code-review + acceptance-
+    // review, round 1). Without this catch, that race propagated out of
+    // this function into the top-level try/catch and aborted the ENTIRE
+    // sweep (every remaining definition/entry/candidate) over one duplicate
+    // row — a blast radius far larger than "no-op." Treated the same way
+    // `lead-routing.ts`'s subscribe path treats its own P2002 (duplicate
+    // subscriber): swallow, log, and let the send stand — the email itself
+    // already went out (or failed) above; only the stamp write raced, and a
+    // race loser here is exactly what "already sent" means (mirrors
+    // `deliverable-fulfillment.ts`'s `stampOutcome` catch-and-log posture
+    // for a stamp write failing outright). Any OTHER error (network/DB-down)
+    // still propagates — this narrows the catch to the one benign race, it
+    // does not paper over a genuine write failure.
+    const isUniqueViolation =
+      err != null && typeof err === "object" && "code" in err &&
+      (err as { code?: unknown }).code === "P2002";
+    if (!isUniqueViolation) throw err;
+    logger.warn(
+      {
+        siteId: candidate.siteId,
+        leadId: candidate.leadId,
+        followUpKey: entry.key,
+      },
+      "[waitlist-followup] stamp write raced a concurrent sweep run (P2002) — treating as already-sent",
+    );
+  }
+  logOutcome(candidate, entry.key, outcome);
+  return outcome;
+}
+
+function addDays(date: Date, days: number): Date {
+  return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+}
+
+export async function runWaitlistFollowUpSweep(
+  opts: RunWaitlistFollowUpSweepOptions = {},
+): Promise<WaitlistFollowUpSweepResult> {
+  const dbError = requireDb();
+  if (dbError) return { ok: false, error: dbError };
+
+  const now = opts.now ?? new Date();
+  const fromAddress =
+    process.env.AILK_FOLLOWUP_EMAIL_FROM ?? process.env.AILK_LEAD_NOTIFICATION_FROM;
+  const audienceId = process.env.RESEND_AUDIENCE_ID;
+
+  const summary: WaitlistFollowUpSweepSummary = {
+    scanned: 0,
+    selected: 0,
+    sent: 0,
+    suppressed: 0,
+    failed: 0,
+    skipped: 0,
+  };
+
+  try {
+    await sweepAllDefinitions(opts, now, fromAddress, audienceId, summary);
+  } catch (err) {
+    // An unexpected DB/network failure mid-loop must degrade to a
+    // structured error, not an unhandled rejection (mirrors abandon-email.ts's
+    // own posture). Progress already stamped on waitlist_followup_sends
+    // before the throw is NOT lost (idempotency means a re-run picks up
+    // where this one stopped); the partial in-memory summary is logged so it
+    // is not silently discarded.
+    const message = err instanceof Error ? err.message : "Unknown error";
+    logger.error(
+      { partialSummary: summary, err: message },
+      "[waitlist-followup] sweep failed mid-run",
+    );
+    return { ok: false, error: { kind: "unexpected_error", message } };
+  }
+
+  return { ok: true, summary };
+}