create-ailk 0.22.0 → 0.24.0

package/templates/apps/api/src/server.ts

@@ -11,18 +11,18 @@
  */
 import cors from "@fastify/cors";
 import rateLimit from "@fastify/rate-limit";
-import { idRegex } from "@working-theory/ids";
 import { logger } from "@working-theory/observability";
 import Fastify from "fastify";
 import type {
   FastifyPluginAsync,
   FastifyPluginCallback,
+  FastifyReply,
   FastifyRequest,
 } from "fastify";
 
 import { config } from "./config/index.js";
 import { isModuleEnabled, servedModules } from "./config/modules.js";
-import { registerErrorSerializer } from "./lib/error-serializer.js";
+import { redactLogPath, registerErrorSerializer } from "./lib/error-serializer.js";
 import { validateLeadCaptureDir } from "./lib/lead-capture-store.js";
 import { registerLicenseKeyStore } from "./lib/license-key-store.js";
 import { requireCommerceClaim } from "./lib/require-commerce-claim.js";
@@ -35,7 +35,10 @@ import {
   buildTrustedKeyDigests,
   DEFAULT_SCHEDULE_PER_KEY_PER_MINUTE,
   DEFAULT_PER_IP_PER_MINUTE_STRICT,
+  DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
   resolveRateLimitIdentity,
+  SITE_KEY_IDENTITY_PREFIX,
+  siteKeyReader,
 } from "./middleware/rate-limit.js";
 import { openapiRoutes } from "./openapi/index.js";
 import {
@@ -65,12 +68,18 @@ import {
 import { getPageRoute } from "./routes/content/get-page.js";
 import { listPagesRoute } from "./routes/content/list-pages.js";
 import { listTypesRoute } from "./routes/content/list-types.js";
+import { offeringsRoute } from "./routes/content/offerings.js";
+import { pricingRoute } from "./routes/content/pricing.js";
 import {
   CONTENT_RATE_LIMIT_AUTH,
   CONTENT_RATE_LIMIT_UNAUTH,
   CONTENT_RATE_LIMIT_WINDOW,
 } from "./routes/content/rate-limit.js";
 import { searchContentRoute } from "./routes/content/search.js";
+import {
+  shownOfferingsRoute,
+  type ShownOfferingsRouteOptions,
+} from "./routes/content/shown-offerings.js";
 import {
   leadCallbackRoute,
   leadCaptureStatusRoute,
@@ -84,6 +93,8 @@ import {
   shouldMountTestAuth,
 } from "./routes/test/auth/session.js";
 import { consentLinkSecretConfigured } from "./services/consent.js";
+import { stripeCatalogSourceFor } from "./services/offerings/source.js";
+import { resolveCallerSite } from "./services/public-site-resolver.js";
 
 /**
  * What a request looks like in a log line — Fastify's own default shape, minus
@@ -99,56 +110,43 @@ import { consentLinkSecretConfigured } from "./services/consent.js";
  * Nothing that identifies a request is lost: a route parameter such as `:id`
  * lives in the PATH and survives. Only the secret after `?` is dropped.
  *
- * #6084 D14 — `GET /v1/checkout/sessions/:id` puts its credential in the
- * PATH, not the query string, so the strip above does not cover it: every
- * request would otherwise write a live `cs_…` Checkout Session id into the
- * log — contradicting D3 and `sessions.ts`'s own stated invariant that only
- * the first 8 characters of a session id ever reach a log line. A path
- * SEGMENT rule (never a substring replace) truncates any `cs_…`-shaped
- * segment to its first 8 characters plus `…`, so it cannot corrupt an
- * unrelated URL.
- *
- * #6216 D11/§ 9 A-3 — the SAME rule now carries a second arm for
- * `lead_…`-shaped segments. Fastify's automatic "incoming request" line is
- * emitted by its internal hook BEFORE any route hook can intervene, so
- * every `GET`/`PATCH .../workspaces/:workspaceId/messages/:leadId` would
- * otherwise write the lead id into the log beside `remoteAddress` —
- * completing exactly the `leadId` ↔ `siteId`/`ip`/`user-agent` correlation
- * `routes/leads/index.ts` and this file's own PII posture refuse. No
- * route-level discipline can fix it; this is the only place that can.
+ * Path segments that are themselves credentials or identifiers — a `cs_…`
+ * Checkout Session id (#6084 D14), a `lead_…` id (#6216 D11), a `person_…` id
+ * (#8438 SEC-8438-10) and a webhook connection token (#8932 D10) — are
+ * redacted by `redactLogPath` (`lib/error-serializer.ts`), the ONE path
+ * redactor this serializer and the global error handler share, so a request
+ * line and an error line can never disagree about what a path may carry.
+ * Fastify's automatic "incoming request" line is emitted by its internal hook
+ * BEFORE any route hook can intervene, so no route-level discipline can fix
+ * it; this is the only place that can.
  */
-const SESSION_ID_LOG_SEGMENT = /^cs_[A-Za-z0-9_]+$/;
-const LEAD_ID_LOG_SEGMENT = idRegex("lead");
-// #8438 SEC-8438-10 — a third arm for `person_…` segments. The consents route
-// (and every other `…/people/:personId…` route) would otherwise write a full
-// Person id into the request log line, beside `remoteAddress`.
-const PERSON_ID_LOG_SEGMENT = idRegex("person");
-
-function redactSensitiveIdSegments(url: string): string {
-  return url
-    .split("/")
-    .map((segment) =>
-      SESSION_ID_LOG_SEGMENT.test(segment) ||
-      LEAD_ID_LOG_SEGMENT.test(segment) ||
-      PERSON_ID_LOG_SEGMENT.test(segment)
-        ? `${segment.slice(0, 8)}…`
-        : segment,
-    )
-    .join("/");
-}
-
 export function requestLogSerializer(request: FastifyRequest) {
-  const raw = request.url;
-  const queryAt = raw.indexOf("?");
-  const path = queryAt === -1 ? raw : raw.slice(0, queryAt);
   return {
     method: request.method,
-    url: redactSensitiveIdSegments(path),
+    url: redactLogPath(request.url),
     host: request.hostname,
     remoteAddress: request.ip,
   };
 }
 
+/**
+ * Fastify's default 404, with the logged path redacted (#8932 SEC-8932-10).
+ * The default handler logs `Route METHOD:URL not found` with the raw URL in
+ * the message, where `requestLogSerializer` never reaches, so a mis-pasted
+ * webhook URL — a trailing slash, a double slash, an extra segment — would
+ * log its connection token on every Stripe retry. The answer is the default
+ * one, byte for byte; only the log line changes.
+ */
+export function notFoundHandler(request: FastifyRequest, reply: FastifyReply) {
+  const { method, url = "" } = request.raw;
+  request.log.info(`Route ${method}:${redactLogPath(url)} not found`);
+  return reply.code(404).send({
+    message: `Route ${method}:${url} not found`,
+    error: "Not Found",
+    statusCode: 404,
+  });
+}
+
 /**
  * Paid-module SLICE entry points, keyed by the export each branch needs
  * (#5182).
@@ -234,6 +232,8 @@ const WORKSPACES_MESSAGES = "./routes/workspaces/messages.js";
 // #7535 — the Inbox submissions and subscribers reads, siblings of
 // WORKSPACES_MESSAGES in the same workspace/multi-tenant scope.
 const WORKSPACES_SUBMISSIONS = "./routes/workspaces/submissions.js";
+// #9170 — the Inbox orders read, the SAME scope.
+const WORKSPACES_ORDERS = "./routes/workspaces/orders.js";
 const WORKSPACES_SUBSCRIBERS = "./routes/workspaces/subscribers.js";
 // #852 D8 — the People reads (the workspace's clients), the SAME scope.
 const WORKSPACES_PEOPLE = "./routes/workspaces/people.js";
@@ -246,6 +246,11 @@ const WORKSPACES_MESSAGES_OUT = "./routes/workspaces/messages-out.js";
 // #8171 D8 — the workspace's Requests read (the inbound member rows), the
 // SAME scope.
 const WORKSPACES_REQUESTS = "./routes/workspaces/requests.js";
+// #9254 DD5 — the workspace's Callbacks read (request-and-confirm rows), the
+// SAME scope.
+const WORKSPACES_CALLBACKS = "./routes/workspaces/callbacks.js";
+// #9287 DD2 — the owner's Start, Get and Extend trial, the SAME scope.
+const WORKSPACES_TRIAL = "./routes/workspaces/trial.js";
 // #7877 D11 — the member reads: auth only, under the SAME module predicate.
 const MEMBER_PIECES = "./routes/member/pieces.js";
 const MEMBER_MESSAGES = "./routes/member/messages.js";
@@ -289,6 +294,7 @@ const ASSETS_UPLOAD = "./routes/assets/upload.js";
 const ASSETS_READ = "./routes/assets/read.js";
 const ASSETS_MANAGE = "./routes/assets/manage.js";
 const BILLING_INDEX = "./routes/billing/index.js";
+const WORKSPACES_OFFERINGS = "./routes/workspaces/offerings.js";
 const WAITLIST_EXPERIMENTS_INDEX = "./routes/waitlist-experiments/index.js";
 const SCHEDULE_INDEX = "./routes/schedule/index.js";
 const FLOWS_INDEX = "./routes/flows/index.js";
@@ -346,6 +352,11 @@ const SLICE_PLUGINS = {
     specifier: WORKSPACES_SUBMISSIONS,
     load: () => import(WORKSPACES_SUBMISSIONS),
   },
+  // #9170 — the Inbox orders read, the SAME scope.
+  workspaceOrderRoutes: {
+    specifier: WORKSPACES_ORDERS,
+    load: () => import(WORKSPACES_ORDERS),
+  },
   workspaceSubscriberRoutes: {
     specifier: WORKSPACES_SUBSCRIBERS,
     load: () => import(WORKSPACES_SUBSCRIBERS),
@@ -366,6 +377,16 @@ const SLICE_PLUGINS = {
     specifier: WORKSPACES_REQUESTS,
     load: () => import(WORKSPACES_REQUESTS),
   },
+  // #9254 DD5 — the Callbacks read, the SAME scope.
+  workspaceCallbackRoutes: {
+    specifier: WORKSPACES_CALLBACKS,
+    load: () => import(WORKSPACES_CALLBACKS),
+  },
+  // #9287 DD2 — the trial routes, the SAME scope.
+  workspaceTrialRoutes: {
+    specifier: WORKSPACES_TRIAL,
+    load: () => import(WORKSPACES_TRIAL),
+  },
   workspacePlanRoutes: {
     specifier: WORKSPACES_PLAN,
     load: () => import(WORKSPACES_PLAN),
@@ -481,6 +502,11 @@ const SLICE_PLUGINS = {
     specifier: BILLING_INDEX,
     load: () => import(BILLING_INDEX),
   },
+  // #8926 D1 — the workspace Offerings routes, multi-tenant only.
+  workspaceOfferingsRoutes: {
+    specifier: WORKSPACES_OFFERINGS,
+    load: () => import(WORKSPACES_OFFERINGS),
+  },
   waitlistExperimentRoutes: {
     specifier: WAITLIST_EXPERIMENTS_INDEX,
     load: () => import(WAITLIST_EXPERIMENTS_INDEX),
@@ -504,6 +530,11 @@ const SLICE_PLUGINS = {
     specifier: SCHEDULE_INDEX,
     load: () => import(SCHEDULE_INDEX),
   },
+  // #8843 D1 — the meetings read; same specifier as its schedule siblings.
+  listMeetingsRoute: {
+    specifier: SCHEDULE_INDEX,
+    load: () => import(SCHEDULE_INDEX),
+  },
   // #6085 — the tenant-guarded appointments read; same specifier as the
   // three anonymous schedule routes above (§ D6, no new SLICE_PLUGINS
   // specifier constant needed).
@@ -539,6 +570,11 @@ const SLICE_PLUGINS = {
     specifier: DELIVERABLES_INDEX,
     load: () => import(DELIVERABLES_INDEX),
   },
+  // #8848 D5 — an ungated file's bytes, in its own `deliverableopen` scope.
+  deliverableOpenRoute: {
+    specifier: DELIVERABLES_INDEX,
+    load: () => import(DELIVERABLES_INDEX),
+  },
   projectListingStartRoute: {
     specifier: PROJECT_LISTINGS_INDEX,
     load: () => import(PROJECT_LISTINGS_INDEX),
@@ -840,6 +876,17 @@ export async function build() {
     (msg) => server.log.warn(msg),
   );
 
+  // #8805 — the sign-up evidence read's site key, verified once per request
+  // and shared by the global ceiling and the `signupevidence` scope below. A
+  // registered, unrevoked spoke key (`resolveCallerSite`, the registry lookup
+  // every spoke-aware route uses) is counted per key; a malformed, unknown or
+  // revoked one, or none, keeps `req.ip`. It decides the bucket only — the
+  // route still serves `resolveSiteWorkspaceId()`.
+  const signUpEvidenceSiteKey = siteKeyReader(async (req) => {
+    const caller = await resolveCallerSite(req);
+    return caller.kind === "spoke" ? caller.spokeId : null;
+  });
+
   // Collect the route table this server registers (#5314).
   //
   // Installed here — after `Fastify()` and before the first `register()` — so
@@ -870,6 +917,7 @@ export async function build() {
   // so connection strings, hostnames, stack traces, and SDK error details
   // never reach the client. Full detail still goes to pino at error level.
   registerErrorSerializer(server);
+  server.setNotFoundHandler(notFoundHandler);
 
   // Register CORS — public read API + the trusted browser origins (#7395).
   // `origin` is ALWAYS a copy of `config.TRUSTED_ORIGINS`, the frozen list
@@ -918,11 +966,23 @@ export async function build() {
   // visitor's own ceiling here too, or a spoke whose visitors share one
   // egress IP would still be capped at this limit in total. For every other
   // request it returns `req.ip`, the plugin's own default key.
+  //
+  // #8805: a sign-up evidence read with a verified site key is keyed
+  // `site,<spokeId>` and let through here — its scope's per-key ceiling is
+  // its one limit, so an anonymous caller spoofing the web's egress address
+  // cannot spend it, and many web instances behind that address share no
+  // IP bucket.
   await server.register(rateLimit, {
     max: CONTENT_RATE_LIMIT_UNAUTH,
     timeWindow: CONTENT_RATE_LIMIT_WINDOW,
-    keyGenerator: (req) =>
-      resolveRateLimitIdentity(req, visitorForwardKeyDigests).identity,
+    keyGenerator: async (req) => {
+      const siteId = await signUpEvidenceSiteKey(req);
+      return siteId === null
+        ? resolveRateLimitIdentity(req, visitorForwardKeyDigests).identity
+        : `${SITE_KEY_IDENTITY_PREFIX}${siteId}`;
+    },
+    allowList: (_req, key) =>
+      typeof key === "string" && key.startsWith(SITE_KEY_IDENTITY_PREFIX),
   });
 
   // Health check
@@ -1122,6 +1182,10 @@ export async function build() {
         await tenantScope.register(await sliceRoutePlugin("sessionRoutes"));
         // Org-billing routes (#3701) — org-scoped read + Stripe customer-portal.
         await tenantScope.register(await sliceRoutePlugin("billingRoutes"));
+        // The workspace Offerings routes (#8926 D1) — the Library → Offerings
+        // tab's read and its selection write, beside the billing routes that
+        // write the Stripe connection they need.
+        await tenantScope.register(await sliceRoutePlugin("workspaceOfferingsRoutes"));
       });
     }
 
@@ -1268,6 +1332,11 @@ export async function build() {
         await tenantScope.register(
           await sliceRoutePlugin("workspaceSubscriberRoutes"),
         );
+        // The Inbox orders read (#9170) — the SAME scope and guard: the
+        // workspace's purchases (list, item read), behind `inbox-read`.
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceOrderRoutes"),
+        );
         // The People reads (#852 D8) — the SAME scope and guard: the
         // workspace's clients and one Person with its derived timeline,
         // behind `people-read` (owner, admin, a granted agent).
@@ -1286,6 +1355,16 @@ export async function build() {
         await tenantScope.register(
           await sliceRoutePlugin("workspaceRequestRoutes"),
         );
+        // #9254 DD5 — the Callbacks read: the request-and-confirm rows the
+        // Inbox lists under Interested, behind `inbox-read`.
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceCallbackRoutes"),
+        );
+        // #9287 DD2 — Start, Get and Extend trial, behind `billing-manage`
+        // (the owner alone; never an agent).
+        await tenantScope.register(
+          await sliceRoutePlugin("workspaceTrialRoutes"),
+        );
         await tenantScope.register(
           await sliceRoutePlugin("workspacePlanRoutes"),
         );
@@ -1385,8 +1464,20 @@ export async function build() {
     await server.register(await sliceRoutePlugin("publicAssetReadRoute"));
   }
   await server.register(listTypesRoute);
-  // Before `listPagesRoute`: `search` must never be read as a `:type`.
+  // Before `listPagesRoute`: `search`, `offerings`, `pricing` and
+  // `shown-offerings` must never be read as a `:type`.
   await server.register(searchContentRoute);
+  // The Organization's Stripe catalog source (#8922), so a stale snapshot
+  // refreshes on the service's bounded, never-forced path (#8924 D7, #9124;
+  // the bounds are `refreshWorkspaceSnapshot`'s). The two agent twins read
+  // the shown set through the same read with these same options, so all
+  // three refresh together (#8933 D5).
+  const shownSetRouteOptions: ShownOfferingsRouteOptions = {
+    sourceFor: stripeCatalogSourceFor,
+  };
+  await server.register(offeringsRoute, shownSetRouteOptions);
+  await server.register(pricingRoute, shownSetRouteOptions);
+  await server.register(shownOfferingsRoute, shownSetRouteOptions);
   await server.register(listPagesRoute);
   await server.register(getPageRoute);
   // The hub's sign-in page names the spoke that sent a visitor (#8790 D2):
@@ -1471,6 +1562,20 @@ export async function build() {
   // (signal-collectors, D-48): gated PDFs and reports.
   if (isModuleEnabled("signal-collectors")) {
     await server.register(await sliceRoutePlugin("deliverableDownloadRoute"));
+    // #8848 D5 — the ungated file read, anonymous and keyed by slug, so it
+    // gets its OWN encapsulated scope: `rateLimitMiddleware` breaks
+    // encapsulation, so it is never installed on the grant route's
+    // registration above, whose budget stays as it is. With the hub's
+    // forward-key digests (the route is on FORWARDED_VISITOR_ROUTES), a
+    // site's proxied reads are counted per visitor (SEC-8848-C).
+    await server.register(async (deliverableOpenScope) => {
+      deliverableOpenScope.register(rateLimitMiddleware, {
+        perIpPerMinute: 60,
+        scope: "deliverableopen",
+        trustedKeyDigests: visitorForwardKeyDigests,
+      });
+      await deliverableOpenScope.register(await sliceRoutePlugin("deliverableOpenRoute"));
+    });
   }
 
   // Webhooks routes — raw-body parser scoped to this sub-router only so the
@@ -1586,15 +1691,20 @@ export async function build() {
     await unsubscribeScope.register(consentUnsubscribeRoute);
   });
   // #8765 D2 — the sign-up agreements' evidence, beside the consent floor:
-  // anonymous, keyless, outside every module gate (sign-up and consent are
-  // never-gate surfaces). Its own scope, `signupevidence`, so an anonymous
-  // burst never shares a bucket with the cookie banner's log (SEC-8765-D).
-  // Its main caller is the web's own server, whose cache keeps it to one call
-  // a minute per enabled locale per instance.
+  // anonymous, outside every module gate (sign-up and consent are never-gate
+  // surfaces). Its own scope, `signupevidence`, so an anonymous burst never
+  // shares a bucket with the cookie banner's log (SEC-8765-D). Its main
+  // caller is the web's own server, whose cache keeps it to one call a minute
+  // per enabled locale per instance. #8805: a call with a verified site key
+  // is counted per key (DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
+  // AILK_RATE_LIMIT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE), never per IP; any
+  // other call keeps 10 a minute per IP.
   await server.register(async (signUpEvidenceScope) => {
     signUpEvidenceScope.register(rateLimitMiddleware, {
       perIpPerMinute: DEFAULT_PER_IP_PER_MINUTE_STRICT,
+      perKeyPerMinute: DEFAULT_SIGNUPEVIDENCE_PER_KEY_PER_MINUTE,
       scope: "signupevidence",
+      siteKeyOf: signUpEvidenceSiteKey,
     });
     await signUpEvidenceScope.register(consentSignUpRoute);
   });
@@ -1772,6 +1882,10 @@ export async function build() {
       await scheduleScope.register(
         await sliceRoutePlugin("meetingTypesRoute"),
       );
+      // #8843 D1 — the meetings read: the same gate and per-IP limit.
+      await scheduleScope.register(
+        await sliceRoutePlugin("listMeetingsRoute"),
+      );
     });
   }
 

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

@@ -29,7 +29,16 @@ jest.mock("@working-theory/observability", () => ({
 }));
 
 import { prisma } from "../../lib/prisma.js";
-import { runAbandonEmailSweep } from "../abandon-email";
+import {
+  ABANDON_CANDIDATE_PAGE_SIZE,
+  runAbandonEmailSweep,
+} from "../abandon-email";
+
+// `flowSession.updateMany` — the dark-mode batch stamp (#9249) — is not on
+// the shared double; installed here the way lead-routing.test.ts installs
+// `lead.count`.
+const mockFlowSessionUpdateMany = jest.fn();
+Object.assign(prisma.flowSession, { updateMany: mockFlowSessionUpdateMany });
 
 // ─── Fixtures ─────────────────────────────────────────────────────────────────
 
@@ -183,15 +192,16 @@ describe("runAbandonEmailSweep", () => {
     (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
       sessionRow(),
     ]);
-    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+    mockFlowSessionUpdateMany.mockResolvedValue({ count: 1 });
 
     const result = await runAbandonEmailSweep({ now: NOW });
 
     expect(mockSendAbandonEmail).not.toHaveBeenCalled();
-    expect(prisma.flowSession.update).toHaveBeenCalledWith({
-      where: { id: SESSION_ID },
+    expect(mockFlowSessionUpdateMany).toHaveBeenCalledWith({
+      where: { id: { in: [SESSION_ID] }, abandonEmailStatus: null },
       data: { abandonEmailStatus: "dark", abandonEmailAt: NOW },
     });
+    expect(prisma.flowSession.update).not.toHaveBeenCalled();
     expect(result).toMatchObject({
       ok: true,
       summary: {
@@ -205,6 +215,113 @@ describe("runAbandonEmailSweep", () => {
     });
   });
 
+  // ── #9249 — dark mode stamps the whole candidate set in ONE updateMany ──
+
+  it("dark mode stamps N≥3 candidates with exactly one flowSession.updateMany, never a per-row update", async () => {
+    const ids = ["flsess_a", "flsess_b", "flsess_c"];
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "dark",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue(
+      ids.map((id) => sessionRow({ id })),
+    );
+    mockFlowSessionUpdateMany.mockResolvedValue({ count: ids.length });
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockFlowSessionUpdateMany).toHaveBeenCalledTimes(1);
+    expect(mockFlowSessionUpdateMany).toHaveBeenCalledWith({
+      // The `abandonEmailStatus: null` guard keeps a row stamped concurrently
+      // from being re-stamped — the same term the candidate read selects on.
+      where: { id: { in: ids }, abandonEmailStatus: null },
+      data: { abandonEmailStatus: "dark", abandonEmailAt: NOW },
+    });
+    expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    expect(mockSendAbandonEmail).not.toHaveBeenCalled();
+    // Per-candidate audit logging is unchanged — one line per session.
+    expect(
+      mockLoggerInfo.mock.calls.filter(
+        ([fields]) => fields.outcome === "dark" && fields.mode === "dark",
+      ),
+    ).toHaveLength(ids.length);
+    // Summary counters report the same numbers as the per-row stamps did.
+    expect(result).toEqual({
+      ok: true,
+      summary: { scanned: 3, selected: 3, dark: 3, sent: 0, failed: 0, skipped: 0 },
+    });
+  });
+
+  it("dark mode with no candidates issues no updateMany at all", async () => {
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "dark",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([]);
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockFlowSessionUpdateMany).not.toHaveBeenCalled();
+    expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      ok: true,
+      summary: { scanned: 0, selected: 0, dark: 0, sent: 0, failed: 0, skipped: 0 },
+    });
+  });
+
+  // ── #9249 — the candidate read is paged ──────────────────────────────────
+
+  it("pages the candidate read with take: ABANDON_CANDIDATE_PAGE_SIZE and processes exactly one page per run", async () => {
+    expect(ABANDON_CANDIDATE_PAGE_SIZE).toBeGreaterThan(0);
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "dark",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+        },
+      }),
+    ]);
+    // The database honours `take`: a run with more candidates than the page
+    // sees exactly one page of them. The rest stay `abandonEmailStatus: null`
+    // and are selected by the next run.
+    const page = Array.from({ length: ABANDON_CANDIDATE_PAGE_SIZE }, (_, i) =>
+      sessionRow({ id: `flsess_${i}` }),
+    );
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue(page);
+    mockFlowSessionUpdateMany.mockResolvedValue({ count: page.length });
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(prisma.flowSession.findMany).toHaveBeenCalledTimes(1);
+    expect(prisma.flowSession.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ take: ABANDON_CANDIDATE_PAGE_SIZE }),
+    );
+    // No second read within the run — the remainder is the next run's.
+    expect(mockFlowSessionUpdateMany).toHaveBeenCalledTimes(1);
+    expect(mockFlowSessionUpdateMany.mock.calls[0][0].where.id.in).toHaveLength(
+      ABANDON_CANDIDATE_PAGE_SIZE,
+    );
+    expect(result).toMatchObject({
+      ok: true,
+      summary: {
+        scanned: ABANDON_CANDIDATE_PAGE_SIZE,
+        selected: ABANDON_CANDIDATE_PAGE_SIZE,
+        dark: ABANDON_CANDIDATE_PAGE_SIZE,
+      },
+    });
+  });
+
   // ── AC2 — enabled mode: selected + sent ──────────────────────────────────
 
   it("enabled mode calls sendAbandonEmail and stamps abandonEmailStatus:'sent'", async () => {