create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/waitlist-signups.test.ts

@@ -0,0 +1,354 @@
+/**
+ * @file waitlist-signups.test.ts
+ *
+ * The respondent read (#4731 D2/D3/D4/D5). Mocked Prisma with a
+ * where-clause-honoring in-memory Lead table (the `waitlist-dashboard.test.ts`
+ * discipline) so the case-insensitive email match, the site scope, the
+ * experimentKey payload filter, and newest-wins ordering are exercised by
+ * what the service actually passes to the DB — not by a static return.
+ * Every fence is asserted: exact seven keys; unverified → NO Lead read;
+ * no lead → signup_not_found; foreign site → signup_not_found; every read
+ * scoped; no other payload key leaves the row.
+ */
+import { readMySignup } from "../waitlist-signups";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    user: { findUnique: jest.fn() },
+    lead: { findFirst: jest.fn() },
+    waitlistScore: { findFirst: jest.fn() },
+    flowSession: { findFirst: jest.fn() },
+  },
+}));
+
+import { prisma } from "../../lib/prisma.js";
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+const SITE = "wksp_00000000-0000-7000-8000-000000000001";
+const OTHER_SITE = "wksp_00000000-0000-7000-8000-0000000000bb";
+const USER_ID = "user_00000000-0000-7000-8000-0000000000a1";
+const EXPERIMENT = "ailk-founder-diagnostic";
+
+const LEAD_OLD = "lead_00000000-0000-7000-8000-0000000000a1";
+const LEAD_NEW = "lead_00000000-0000-7000-8000-0000000000a2";
+const LEAD_FOREIGN = "lead_00000000-0000-7000-8000-0000000000b1";
+
+type LeadRow = {
+  id: string;
+  siteId: string;
+  email: string;
+  payload: Record<string, unknown>;
+  createdAt: Date;
+};
+
+const LEADS: LeadRow[] = [
+  {
+    id: LEAD_OLD,
+    siteId: SITE,
+    // Stored AS TYPED (mixed case) — the D3 normalization case.
+    email: "Alice@Example.com",
+    payload: {
+      experimentKey: EXPERIMENT,
+      waitlistKey: "early_bird",
+      q3: "old answer",
+      name: "Alice",
+      url: "https://alice.example",
+      email: "Alice@Example.com",
+    },
+    createdAt: new Date("2026-09-01T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_NEW,
+    siteId: SITE,
+    email: "alice@example.com",
+    payload: {
+      experimentKey: EXPERIMENT,
+      waitlistKey: "general",
+      q1: "solo_builder",
+      q3: "Our site never ships.",
+      name: "Alice",
+      url: "https://alice.example",
+      email: "alice@example.com",
+      aeoScore: { status: "unavailable", reason: "crawl_failed", message: "x" },
+    },
+    createdAt: new Date("2026-09-03T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_FOREIGN,
+    siteId: OTHER_SITE,
+    email: "alice@example.com",
+    payload: { experimentKey: EXPERIMENT, waitlistKey: "foreign", q3: "foreign" },
+    createdAt: new Date("2026-09-04T00:00:00.000Z"),
+  },
+];
+
+const SCORES = [
+  { leadId: LEAD_NEW, siteId: SITE, experimentKey: EXPERIMENT, tier: "hot", score: 12 },
+  { leadId: LEAD_OLD, siteId: SITE, experimentKey: EXPERIMENT, tier: "warm", score: 7 },
+  { leadId: LEAD_FOREIGN, siteId: OTHER_SITE, experimentKey: EXPERIMENT, tier: "hot", score: 99 },
+];
+
+const AEO_UNAVAILABLE = { status: "unavailable", reason: "crawl_failed", message: "This URL cannot be scored." };
+
+const SESSIONS = [
+  {
+    leadId: LEAD_NEW,
+    siteId: SITE,
+    aeoScore: AEO_UNAVAILABLE,
+    completedAt: new Date("2026-09-03T00:00:05.000Z"),
+  },
+  { leadId: LEAD_OLD, siteId: SITE, aeoScore: null, completedAt: new Date("2026-09-01T00:00:05.000Z") },
+];
+
+// ── A where-clause-honoring in-memory matcher ────────────────────────────────
+
+type Where = Record<string, unknown>;
+
+function matchesLead(row: LeadRow, where: Where): boolean {
+  for (const [key, cond] of Object.entries(where)) {
+    if (key === "email") {
+      const c = cond as { equals: string; mode?: string };
+      const stored = c.mode === "insensitive" ? row.email.toLowerCase() : row.email;
+      const wanted = c.mode === "insensitive" ? c.equals.toLowerCase() : c.equals;
+      if (stored !== wanted) return false;
+      continue;
+    }
+    if (key === "payload") {
+      const { path, equals } = cond as { path: string[]; equals: unknown };
+      if (row.payload[path[0] as string] !== equals) return false;
+      continue;
+    }
+    if ((row as Record<string, unknown>)[key] !== cond) return false;
+  }
+  return true;
+}
+
+function matchesScalar(row: Record<string, unknown>, where: Where): boolean {
+  for (const [key, cond] of Object.entries(where)) {
+    if (cond !== null && typeof cond === "object" && "not" in (cond as object)) {
+      if (row[key] === (cond as { not: unknown }).not) return false;
+      continue;
+    }
+    if (row[key] !== cond) return false;
+  }
+  return true;
+}
+
+function installFixtureMocks(): void {
+  (prisma.lead.findFirst as jest.Mock).mockImplementation(
+    ({ where, orderBy }: { where: Where; orderBy?: { createdAt: "asc" | "desc" } }) => {
+      const rows = LEADS.filter((r) => matchesLead(r, where));
+      if (orderBy?.createdAt === "desc") rows.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+      else rows.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+      const hit = rows[0];
+      return Promise.resolve(hit ? { id: hit.id, payload: hit.payload, createdAt: hit.createdAt } : null);
+    },
+  );
+  (prisma.waitlistScore.findFirst as jest.Mock).mockImplementation(({ where }: { where: Where }) => {
+    const hit = SCORES.find((r) => matchesScalar(r, where));
+    return Promise.resolve(hit ? { tier: hit.tier, score: hit.score } : null);
+  });
+  (prisma.flowSession.findFirst as jest.Mock).mockImplementation(({ where }: { where: Where }) => {
+    const hit = SESSIONS.find((r) => matchesScalar(r, where));
+    return Promise.resolve(hit ? { aeoScore: hit.aeoScore, completedAt: hit.completedAt } : null);
+  });
+}
+
+function user(overrides?: Partial<{ email: string; emailVerified: boolean }>) {
+  return {
+    id: USER_ID,
+    email: overrides?.email ?? "alice@example.com",
+    emailVerified: overrides?.emailVerified ?? true,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env.AILK_SITE_ID = SITE;
+  installFixtureMocks();
+});
+
+afterAll(() => {
+  delete process.env.AILK_SITE_ID;
+});
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("readMySignup — the verified, found path (D5)", () => {
+  it("returns EXACTLY the seven contract keys and only q3 under answers", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error("unreachable");
+    expect(Object.keys(result.value).sort()).toEqual(
+      ["answers", "aeoScore", "completedAt", "experimentKey", "score", "tier", "waitlistKey"].sort(),
+    );
+    expect(Object.keys(result.value.answers)).toEqual(["q3"]);
+    expect(result.value).toEqual({
+      experimentKey: EXPERIMENT,
+      waitlistKey: "general",
+      completedAt: "2026-09-03T00:00:05.000Z",
+      tier: "hot",
+      score: 12,
+      aeoScore: AEO_UNAVAILABLE,
+      answers: { q3: "Our site never ships." },
+    });
+    // Nothing else from the payload leaves the row.
+    const serialized = JSON.stringify(result.value);
+    for (const leaked of ["name", "url", "q1", "solo_builder", "alice.example", "@example.com"]) {
+      expect(serialized).not.toContain(leaked);
+    }
+  });
+
+  it("reads the User exactly as lead-promotion.ts does (id, email, emailVerified by id)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(prisma.user.findUnique).toHaveBeenCalledWith({
+      where: { id: USER_ID },
+      select: { id: true, email: true, emailVerified: true },
+    });
+  });
+
+  it("newest createdAt wins when two leads match (AC-5)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok && result.value.waitlistKey).toBe("general"); // LEAD_NEW, not LEAD_OLD
+    expect(prisma.lead.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({ orderBy: { createdAt: "desc" } }),
+    );
+  });
+
+  it("matches a mixed-case stored Lead.email case-insensitively on the trimmed user email (D3)", async () => {
+    // Only the OLD lead carries the mixed-case stored email; pick it by
+    // restricting the fixture to that row.
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user({ email: "  ALICE@example.COM " }));
+    (prisma.lead.findFirst as jest.Mock).mockImplementation(({ where }: { where: Where }) => {
+      const hit = LEADS.filter((r) => r.id === LEAD_OLD).find((r) => matchesLead(r, where));
+      return Promise.resolve(hit ? { id: hit.id, payload: hit.payload, createdAt: hit.createdAt } : null);
+    });
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok && result.value.waitlistKey).toBe("early_bird");
+    const call = (prisma.lead.findFirst as jest.Mock).mock.calls[0][0] as { where: Where };
+    expect(call.where.email).toEqual({ equals: "alice@example.com", mode: "insensitive" });
+  });
+
+  it("scopes EVERY read to currentSiteId() and filters the Lead by payload.experimentKey (AC-7)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    await readMySignup(USER_ID, EXPERIMENT);
+
+    const leadWhere = (prisma.lead.findFirst as jest.Mock).mock.calls[0][0].where as Where;
+    expect(leadWhere.siteId).toBe(SITE);
+    expect(leadWhere.payload).toEqual({ path: ["experimentKey"], equals: EXPERIMENT });
+    const scoreWhere = (prisma.waitlistScore.findFirst as jest.Mock).mock.calls[0][0].where as Where;
+    expect(scoreWhere).toEqual({ leadId: LEAD_NEW, siteId: SITE, experimentKey: EXPERIMENT });
+    const sessionWhere = (prisma.flowSession.findFirst as jest.Mock).mock.calls[0][0].where as Where;
+    expect(sessionWhere).toEqual({ leadId: LEAD_NEW, siteId: SITE, completedAt: { not: null } });
+  });
+
+  it("a lead that exists only at another site is signup_not_found (never cross-site)", async () => {
+    process.env.AILK_SITE_ID = "wksp_00000000-0000-7000-8000-0000000000cc";
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result).toEqual({
+      ok: false,
+      error: { kind: "signup_not_found", message: "Signup not found" },
+    });
+  });
+
+  it("returns null tier/score when the fail-soft score row is absent, and null aeoScore when unparsable", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+    (prisma.waitlistScore.findFirst as jest.Mock).mockResolvedValue(null);
+    (prisma.flowSession.findFirst as jest.Mock).mockResolvedValue({
+      aeoScore: { status: "bogus" },
+      completedAt: new Date("2026-09-03T00:00:05.000Z"),
+    });
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok && result.value.tier).toBeNull();
+    expect(result.ok && result.value.score).toBeNull();
+    expect(result.ok && result.value.aeoScore).toBeNull();
+  });
+
+  it("falls back to Lead.createdAt for completedAt when no completing session exists, and q3 null when absent", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+    (prisma.flowSession.findFirst as jest.Mock).mockResolvedValue(null);
+    (prisma.lead.findFirst as jest.Mock).mockResolvedValue({
+      id: LEAD_NEW,
+      payload: { experimentKey: EXPERIMENT, waitlistKey: "general", q3: 42 },
+      createdAt: new Date("2026-09-03T00:00:00.000Z"),
+    });
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok && result.value.completedAt).toBe("2026-09-03T00:00:00.000Z");
+    expect(result.ok && result.value.answers.q3).toBeNull();
+  });
+});
+
+describe("readMySignup — the refusals (D2/D4)", () => {
+  it("email_unverified: refuses BEFORE any Lead read (AC-3)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user({ emailVerified: false }));
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(result.ok).toBe(false);
+    expect(!result.ok && result.error.kind).toBe("email_unverified");
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+    expect(prisma.waitlistScore.findFirst).not.toHaveBeenCalled();
+    expect(prisma.flowSession.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("not_found_user: no User row → no Lead read", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(!result.ok && result.error.kind).toBe("not_found_user");
+    expect(prisma.lead.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("signup_not_found: a different email owns the leads (AC-4)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user({ email: "bob@example.com" }));
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(!result.ok && result.error.kind).toBe("signup_not_found");
+    expect(prisma.waitlistScore.findFirst).not.toHaveBeenCalled();
+  });
+
+  it("signup_not_found: no lead for this experimentKey (AC-4)", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+
+    const result = await readMySignup(USER_ID, "some-other-experiment");
+
+    expect(!result.ok && result.error.kind).toBe("signup_not_found");
+  });
+
+  it("signup_not_found: a corrupt lead missing waitlistKey is not-found, never an out-of-contract value", async () => {
+    (prisma.user.findUnique as jest.Mock).mockResolvedValue(user());
+    (prisma.lead.findFirst as jest.Mock).mockResolvedValue({
+      id: LEAD_NEW,
+      payload: { experimentKey: EXPERIMENT, q3: "x" },
+      createdAt: new Date("2026-09-03T00:00:00.000Z"),
+    });
+
+    const result = await readMySignup(USER_ID, EXPERIMENT);
+
+    expect(!result.ok && result.error.kind).toBe("signup_not_found");
+    expect(prisma.waitlistScore.findFirst).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/api/src/services/abandon-email.ts

@@ -0,0 +1,307 @@
+/**
+ * @file abandon-email.ts
+ * @description The abandon-email sweep service (#3962 D4).
+ *
+ * `runAbandonEmailSweep` is the one entry point: select partial `FlowSession`
+ * rows past their flow's configured delay, dispatch per the flow's send
+ * policy (dark → audit-only stamp; enabled → send + stamp), and record the
+ * outcome on the session row (D5's idempotency + audit guarantee). Invoked
+ * by the CLI entry (`src/bin/abandon-sweep.ts`) on an operator-supplied
+ * cadence — this service itself is stateless and has no timer of its own
+ * (D1: no queue/cron infrastructure).
+ *
+ * Mirrors the lead-routing/flow-engine house shape: type-result returns,
+ * mocked-dep tests, PII-safe logging via @working-theory/observability
+ * (siteId/flowSlug/sessionId/mode/outcome only — never email/state values).
+ */
+
+import { sendAbandonEmail } from "@working-theory/email";
+import { logger } from "@working-theory/observability";
+import {
+  flowConfigSchema,
+  type AbandonEmailConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type AbandonEmailSweepSummary = {
+  scanned: number;
+  selected: number;
+  sent: number;
+  dark: number;
+  failed: number;
+  skipped: number;
+};
+
+export type AbandonEmailSweepError = {
+  kind: "flows_not_configured" | "unexpected_error";
+  message: string;
+};
+
+export type AbandonEmailSweepResult =
+  | { ok: true; summary: AbandonEmailSweepSummary }
+  | { ok: false; error: AbandonEmailSweepError };
+
+export type RunAbandonEmailSweepOptions = {
+  siteId?: string;
+  now?: Date;
+};
+
+type FlowDefinitionRow = {
+  id: string;
+  siteId: string;
+  slug: string;
+  config: unknown;
+};
+
+type AbandonCandidateRow = {
+  id: string;
+  siteId: string;
+  flowSlug: string;
+  email: string | null;
+  locale: string | null;
+};
+
+// ─── DB-required guard (mirrors flow-engine.ts's requireDb) ────────────────────
+
+const FLOWS_NOT_CONFIGURED_ERROR = {
+  kind: "flows_not_configured" as const,
+  message: "Flows are not configured.",
+};
+
+function requireDb(): AbandonEmailSweepError | null {
+  if (!process.env.DATABASE_URL) return FLOWS_NOT_CONFIGURED_ERROR;
+  return null;
+}
+
+// ─── PII-safe outcome logging ───────────────────────────────────────────────────
+
+type AbandonOutcome = "dark" | "skipped" | "sent" | "failed";
+
+const OUTCOME_MESSAGE: Record<AbandonOutcome, string> = {
+  dark: "[abandon-email] session selected — dark mode, audit-only",
+  skipped: "[abandon-email] enabled candidate skipped — no from-address configured",
+  sent: "[abandon-email] session selected — sent",
+  failed: "[abandon-email] session selected — send failed",
+};
+
+/**
+ * The one shape every outcome logs (siteId/flowSlug/sessionId/mode/outcome —
+ * never email/state values, per this file's PII boundary).
+ */
+function logOutcome(
+  session: AbandonCandidateRow,
+  mode: AbandonEmailConfig["mode"],
+  outcome: AbandonOutcome,
+): void {
+  logger.info(
+    {
+      siteId: session.siteId,
+      flowSlug: session.flowSlug,
+      sessionId: session.id,
+      mode,
+      outcome,
+    },
+    OUTCOME_MESSAGE[outcome],
+  );
+}
+
+// ─── Copy resolution (D6) ───────────────────────────────────────────────────────
+
+/**
+ * `copy[session.locale ?? liveConfig.defaultLocale] ?? copy[liveConfig.defaultLocale]`
+ * (D6). `defaultLocale` is a required key on every LocalizedString the
+ * `abandonEmailSchema` superRefine walk enforces, so the final fallback is
+ * always resolvable for a schema-valid config.
+ */
+function resolveCopy(
+  copy: Record<string, string>,
+  sessionLocale: string | null,
+  defaultLocale: string,
+): string {
+  const locale = sessionLocale ?? defaultLocale;
+  return copy[locale] ?? copy[defaultLocale] ?? "";
+}
+
+/** Link = resumeUrl + '?fs=' + sessionId — no other session data (D7, no PII). */
+function buildResumeLink(
+  resumeUrl: string | undefined,
+  sessionId: string,
+): string | undefined {
+  if (!resumeUrl) return undefined;
+  return `${resumeUrl}?fs=${sessionId}`;
+}
+
+// ─── 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 (code-review finding on #3962's acceptance PR: an unhandled
+ * rejection mid-sweep should degrade to a structured error with the partial
+ * progress visible, not vanish).
+ */
+async function sweepAllDefinitions(
+  opts: RunAbandonEmailSweepOptions,
+  now: Date,
+  fromAddress: string | undefined,
+  summary: AbandonEmailSweepSummary,
+): 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[];
+
+  for (const definition of definitions) {
+    const parsedConfig = flowConfigSchema.safeParse(definition.config);
+    if (!parsedConfig.success) {
+      // Surface, do not swallow (code-review finding on #3962's acceptance
+      // PR) — every sibling path in this feature area (serveFlow /
+      // upsertFlowDefinition in flow-engine.ts) returns an explicit error on
+      // a config-parse failure; a stored config that has drifted from the
+      // schema must not silently stop that flow's abandon-email policy from
+      // ever running again with no operator-visible signal.
+      logger.warn(
+        {
+          siteId: definition.siteId,
+          flowSlug: definition.slug,
+          zodIssue: parsedConfig.error.issues[0]?.message,
+        },
+        "[abandon-email] skipping flow — stored config failed schema validation",
+      );
+      continue;
+    }
+    const config = parsedConfig.data;
+    const policy: AbandonEmailConfig | undefined = config.abandonEmail;
+    // Block absent = abandon email OFF for this flow — never selected (D2).
+    if (!policy) continue;
+
+    const cutoff = new Date(now.getTime() - policy.delayMinutes * 60_000);
+
+    // The #3956 D2 partial-lead query (email != null AND completedAt == null)
+    // plus the not-yet-processed and delay-window terms (D4/D5).
+    const candidates = (await prisma.flowSession.findMany({
+      where: {
+        flowId: definition.id,
+        email: { not: null },
+        completedAt: null,
+        abandonEmailStatus: null,
+        updatedAt: { lte: cutoff },
+      },
+      select: {
+        id: true,
+        siteId: true,
+        flowSlug: true,
+        email: true,
+        locale: true,
+      },
+    })) as AbandonCandidateRow[];
+
+    summary.scanned += candidates.length;
+
+    for (const session of candidates) {
+      summary.selected += 1;
+
+      if (policy.mode === "dark") {
+        await prisma.flowSession.update({
+          where: { id: session.id },
+          data: { abandonEmailStatus: "dark", abandonEmailAt: now },
+        });
+        summary.dark += 1;
+        logOutcome(session, policy.mode, "dark");
+        continue;
+      }
+
+      // mode:'enabled' — an env gap must not consume the one send: leave the
+      // candidate UNSTAMPED so a later configured run still sends it (D4).
+      if (!fromAddress) {
+        summary.skipped += 1;
+        logOutcome(session, policy.mode, "skipped");
+        continue;
+      }
+
+      const subject = resolveCopy(
+        policy.copy.subject,
+        session.locale,
+        config.defaultLocale,
+      );
+      const body = resolveCopy(
+        policy.copy.body,
+        session.locale,
+        config.defaultLocale,
+      );
+      const cta = policy.copy.cta
+        ? resolveCopy(policy.copy.cta, session.locale, config.defaultLocale)
+        : undefined;
+      const resumeLink = buildResumeLink(policy.resumeUrl, session.id);
+
+      const sendResult = await sendAbandonEmail({
+        // `email: { not: null }` in the WHERE clause above guarantees this.
+        to: session.email as string,
+        fromAddress,
+        subject,
+        body,
+        ...(cta !== undefined && { cta }),
+        ...(resumeLink !== undefined && { resumeLink }),
+      });
+
+      if (sendResult.ok) {
+        await prisma.flowSession.update({
+          where: { id: session.id },
+          data: { abandonEmailStatus: "sent", abandonEmailAt: now },
+        });
+        summary.sent += 1;
+        logOutcome(session, policy.mode, "sent");
+      } else {
+        // Terminal to the sweep — no auto-retry (D5); clearing the stamp is
+        // the deliberate operator retry.
+        await prisma.flowSession.update({
+          where: { id: session.id },
+          data: { abandonEmailStatus: "failed", abandonEmailAt: now },
+        });
+        summary.failed += 1;
+        logOutcome(session, policy.mode, "failed");
+      }
+    }
+  }
+}
+
+export async function runAbandonEmailSweep(
+  opts: RunAbandonEmailSweepOptions = {},
+): Promise<AbandonEmailSweepResult> {
+  const dbError = requireDb();
+  if (dbError) return { ok: false, error: dbError };
+
+  const now = opts.now ?? new Date();
+  const fromAddress =
+    process.env.AILK_ABANDON_EMAIL_FROM ??
+    process.env.AILK_LEAD_NOTIFICATION_FROM;
+
+  const summary: AbandonEmailSweepSummary = {
+    scanned: 0,
+    selected: 0,
+    sent: 0,
+    dark: 0,
+    failed: 0,
+    skipped: 0,
+  };
+
+  try {
+    await sweepAllDefinitions(opts, now, fromAddress, summary);
+  } catch (err) {
+    // An unexpected DB/network failure mid-loop must degrade to a
+    // structured error, not an unhandled rejection (code-review finding on
+    // #3962's acceptance PR) — the CLI entry's own try/catch expects this
+    // shape. Progress already stamped on session rows before the throw is
+    // NOT lost (D5's 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 }, "[abandon-email] sweep failed mid-run");
+    return { ok: false, error: { kind: "unexpected_error", message } };
+  }
+
+  return { ok: true, summary };
+}