create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,1314 @@
+// oss: false
+/**
+ * @file waitlist-dashboard.test.ts
+ *
+ * The B0 service layer (#4665 D2/D3/D4/D5, #4671). Mocked Prisma (a
+ * where-clause-honoring in-memory matcher, mirroring
+ * `routes/workspaces/__tests__/tenant-isolation.test.ts`'s discipline): the
+ * platform-operator predicate both ways (sentinel-org owner -> "all";
+ * sentinel-org admin, non-sentinel owner -> "site"); every query carries the
+ * scope; a foreign lead is `not_found`; D4 arithmetic on a fixture (raw /
+ * qualified / null cases / "(direct)" / "(other)" / multi counted per
+ * value); no write verb reachable.
+ */
+import { waitlistDashboardListSchema } from "@working-theory/validation";
+
+import { MAX_AGGREGATION_ROWS } from "../answer-distributions";
+
+import {
+  getExperimentComparison,
+  getSignup,
+  isPlatformOperator,
+  listExperiments,
+  listSignups,
+  resolveWaitlistReadScope,
+  WAITLIST_DASHBOARD_ROLES,
+} from "../waitlist-dashboard";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    waitlistExperiment: { findMany: jest.fn(), findFirst: jest.fn() },
+    lead: { findMany: jest.fn(), findFirst: jest.fn() },
+    waitlistScore: { findMany: jest.fn(), findFirst: jest.fn(), findUnique: jest.fn() },
+    flowSession: { findMany: jest.fn() },
+    flowCheckout: { findMany: jest.fn() },
+  },
+}));
+
+// #4861 — the register engine is wrapped, not replaced: the REAL `recommend`
+// runs, through a `jest.fn` so the per-call count is observable (spec §5.1
+// AC-1). Every existing test's behaviour is byte-identical.
+jest.mock("@working-theory/validation", () => {
+  const actual = jest.requireActual("@working-theory/validation");
+  return { ...actual, recommend: jest.fn(actual.recommend) };
+});
+
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "../../lib/prisma.js";
+import type { TenantContext } from "../tenant-context";
+
+// ── Fixture ids ──────────────────────────────────────────────────────────────
+
+const ORG_SENTINEL = "org_00000000-0000-7000-8000-000000000001";
+const WS_A = "wksp_00000000-0000-7000-8000-000000000001"; // sentinel org's own site
+// A genuinely non-sentinel org id — a real (non-zero-timestamp) v7 uuid, so
+// `isSentinel` correctly reads false for it (unlike the all-zero-timestamp
+// sentinel range `00000000-0000-7000-8000-…`).
+const ORG_B = "org_01991234-5678-7000-8000-0000000000bb";
+const WS_B = "wksp_00000000-0000-7000-8000-0000000000bb";
+
+const EXP_A = "wlexp_00000000-0000-7000-8000-0000000000aa"; // qualifying, site A
+const EXP_B = "wlexp_00000000-0000-7000-8000-0000000000bb"; // lead-capture, site B
+
+// ── Config fixtures (waitlistExperimentConfigSchema-shaped) ──────────────────
+
+const en = (s: string) => ({ en: s });
+
+const CONFIG_A = {
+  key: "founder-diagnostic",
+  mode: "qualifying" as const,
+  status: "live" as const,
+  waitlists: [
+    { key: "early_bird", flowSlug: "founder-diagnostic-early" },
+    { key: "general", flowSlug: "founder-diagnostic-general", entryPageKey: "gen-page" },
+  ],
+  questionSet: {
+    version: 1 as const,
+    questions: [
+      {
+        id: "role",
+        prompt: en("Role?"),
+        answerType: "single" as const,
+        options: [
+          { value: "founder", label: en("Founder") },
+          { value: "other", label: en("Other") },
+        ],
+      },
+      { id: "notes", prompt: en("Notes?"), answerType: "text" as const, minLength: 1 },
+    ],
+  },
+  scoring: {
+    version: 1 as const,
+    points: [
+      {
+        name: "role_pt",
+        question: "role",
+        kind: "optionWeights" as const,
+        weights: { founder: 5, other: 0 },
+      },
+    ],
+    scores: { total: { sum: ["role_pt"] } },
+    tiers: [
+      { key: "hot", when: { score: "total", gte: 5 } },
+      { key: "cold", when: { score: "total", gte: 0 } },
+    ],
+    default: "cold",
+    serviceableExcludes: ["cold"],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: {
+      early_bird: { campaign: "eb-campaign", channels: ["organic"] },
+      general: { campaign: "gen-campaign", channels: ["organic"] },
+    },
+  },
+  stripeConfigRef: null,
+};
+
+const CONFIG_B = {
+  key: "lead-capture-exp",
+  mode: "lead-capture" as const,
+  status: "draft" as const,
+  waitlists: [{ key: "general", flowSlug: "lead-capture-general" }],
+  questionSet: {
+    version: 1 as const,
+    questions: [{ id: "role", prompt: en("Role?"), answerType: "text" as const, minLength: 1 }],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: { general: { campaign: "lc-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: null,
+};
+
+const EXPERIMENTS = [
+  {
+    id: EXP_A,
+    siteId: WS_A,
+    key: CONFIG_A.key,
+    mode: CONFIG_A.mode,
+    status: CONFIG_A.status,
+    config: CONFIG_A,
+    createdAt: new Date("2026-08-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-08-01T00:00:00.000Z"),
+  },
+  {
+    id: EXP_B,
+    siteId: WS_B,
+    key: CONFIG_B.key,
+    mode: CONFIG_B.mode,
+    status: CONFIG_B.status,
+    config: CONFIG_B,
+    createdAt: new Date("2026-08-02T00:00:00.000Z"),
+    updatedAt: new Date("2026-08-02T00:00:00.000Z"),
+  },
+];
+
+// ── Lead fixtures for EXP_A (four signups across two waitlists) ─────────────
+
+const LEAD_1 = "lead_00000000-0000-7000-8000-000000000001"; // early_bird, founder, twitter -> hot
+const LEAD_2 = "lead_00000000-0000-7000-8000-000000000002"; // early_bird, other, direct -> cold
+const LEAD_3 = "lead_00000000-0000-7000-8000-000000000003"; // general, founder, direct, unscored
+const LEAD_4 = "lead_00000000-0000-7000-8000-000000000004"; // general, weird-value (-> other), twitter -> cold
+const LEAD_5 = "lead_00000000-0000-7000-8000-000000000005"; // EXP_B's one signup
+
+const LEADS = [
+  {
+    id: LEAD_1,
+    siteId: WS_A,
+    email: "one@example.com",
+    source: "flow:founder-diagnostic-early",
+    payload: {
+      experimentKey: "founder-diagnostic",
+      waitlistKey: "early_bird",
+      role: "founder",
+      notes: "hi",
+      utm_source: "twitter",
+    },
+    createdAt: new Date("2026-08-10T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_2,
+    siteId: WS_A,
+    email: "two@example.com",
+    source: "flow:founder-diagnostic-early",
+    payload: {
+      experimentKey: "founder-diagnostic",
+      waitlistKey: "early_bird",
+      role: "other",
+    },
+    createdAt: new Date("2026-08-11T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_3,
+    siteId: WS_A,
+    email: "three@example.com",
+    source: "flow:founder-diagnostic-general",
+    payload: {
+      experimentKey: "founder-diagnostic",
+      waitlistKey: "general",
+      role: "founder",
+    },
+    createdAt: new Date("2026-08-12T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_4,
+    siteId: WS_A,
+    email: "four@example.com",
+    source: "flow:founder-diagnostic-general",
+    payload: {
+      experimentKey: "founder-diagnostic",
+      waitlistKey: "general",
+      role: "weird-value",
+      utm_source: "twitter",
+    },
+    createdAt: new Date("2026-08-13T00:00:00.000Z"),
+  },
+  {
+    id: LEAD_5,
+    siteId: WS_B,
+    email: "five@example.com",
+    source: "flow:lead-capture-general",
+    payload: { experimentKey: "lead-capture-exp", waitlistKey: "general", role: "solo" },
+    createdAt: new Date("2026-08-14T00:00:00.000Z"),
+  },
+];
+
+const SCORES = [
+  {
+    leadId: LEAD_1,
+    siteId: WS_A,
+    experimentKey: "founder-diagnostic",
+    tier: "hot",
+    score: 5,
+    categoryScores: { total: 5 },
+    ruleTrace: { fired: ["role_pt"] },
+    updatedAt: new Date("2026-08-10T01:00:00.000Z"),
+  },
+  {
+    leadId: LEAD_2,
+    siteId: WS_A,
+    experimentKey: "founder-diagnostic",
+    tier: "cold",
+    score: 0,
+    categoryScores: { total: 0 },
+    ruleTrace: { fired: [] },
+    updatedAt: new Date("2026-08-11T01:00:00.000Z"),
+  },
+  {
+    leadId: LEAD_4,
+    siteId: WS_A,
+    experimentKey: "founder-diagnostic",
+    tier: "cold",
+    score: 0,
+    categoryScores: { total: 0 },
+    ruleTrace: { fired: [] },
+    updatedAt: new Date("2026-08-13T01:00:00.000Z"),
+  },
+  // LEAD_3 is intentionally unscored — A2 has not run for it yet.
+];
+
+// ── A generic, where-clause-honoring in-memory matcher ───────────────────────
+
+type Row = Record<string, unknown>;
+type Where = Record<string, unknown>;
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+  return a === b;
+}
+function lessThan(a: unknown, b: unknown): boolean {
+  if (a instanceof Date && b instanceof Date) return a.getTime() < b.getTime();
+  return (a as never) < (b as never);
+}
+
+function matchesWhere(row: Row, where: Where): boolean {
+  for (const [key, cond] of Object.entries(where)) {
+    if (key === "OR") {
+      if (!(cond as Where[]).some((w) => matchesWhere(row, w))) return false;
+      continue;
+    }
+    if (key === "AND") {
+      if (!(cond as Where[]).every((w) => matchesWhere(row, w))) return false;
+      continue;
+    }
+    if (key === "payload") {
+      const { path, equals } = cond as { path: string[]; equals: unknown };
+      const payload = row.payload as Record<string, unknown> | undefined;
+      const value = payload ? payload[path[0] as string] : undefined;
+      if (!valuesEqual(value, equals)) return false;
+      continue;
+    }
+    const rowValue = row[key];
+    if (cond !== null && typeof cond === "object" && !Array.isArray(cond) && !(cond instanceof Date)) {
+      const condObj = cond as Record<string, unknown>;
+      if ("in" in condObj) {
+        if (!(condObj.in as unknown[]).some((v) => valuesEqual(v, rowValue))) return false;
+        continue;
+      }
+      if ("lt" in condObj) {
+        if (!lessThan(rowValue, condObj.lt)) return false;
+        continue;
+      }
+    }
+    if (!valuesEqual(rowValue, cond)) return false;
+  }
+  return true;
+}
+
+function sortRows(rows: Row[], orderBy: unknown): Row[] {
+  if (!orderBy) return rows;
+  const orders = Array.isArray(orderBy) ? orderBy : [orderBy];
+  return [...rows].sort((a, b) => {
+    for (const ord of orders as Array<Record<string, "asc" | "desc">>) {
+      const [field, dir] = Object.entries(ord)[0] as [string, "asc" | "desc"];
+      const av = a[field];
+      const bv = b[field];
+      let cmp: number;
+      if (av instanceof Date && bv instanceof Date) cmp = av.getTime() - bv.getTime();
+      else if ((av as never) < (bv as never)) cmp = -1;
+      else if ((av as never) > (bv as never)) cmp = 1;
+      else cmp = 0;
+      if (dir === "desc") cmp = -cmp;
+      if (cmp !== 0) return cmp;
+    }
+    return 0;
+  });
+}
+
+function installFixtureMocks(): void {
+  (prisma.waitlistExperiment.findMany as jest.Mock).mockImplementation(
+    ({ where }: { where?: Where }) =>
+      Promise.resolve(sortRows(EXPERIMENTS.filter((e) => matchesWhere(e, where ?? {})), { createdAt: "desc" })),
+  );
+  (prisma.waitlistExperiment.findFirst as jest.Mock).mockImplementation(
+    ({ where }: { where?: Where }) =>
+      Promise.resolve(EXPERIMENTS.find((e) => matchesWhere(e, where ?? {})) ?? null),
+  );
+  (prisma.lead.findMany as jest.Mock).mockImplementation(
+    ({ where, orderBy, take }: { where?: Where; orderBy?: unknown; take?: number }) => {
+      let rows = LEADS.filter((l) => matchesWhere(l, where ?? {}));
+      rows = sortRows(rows, orderBy);
+      if (typeof take === "number") rows = rows.slice(0, take);
+      return Promise.resolve(rows);
+    },
+  );
+  (prisma.lead.findFirst as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(LEADS.find((l) => matchesWhere(l, where ?? {})) ?? null),
+  );
+  (prisma.waitlistScore.findMany as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(SCORES.filter((s) => matchesWhere(s, where ?? {}))),
+  );
+  (prisma.waitlistScore.findFirst as jest.Mock).mockImplementation(({ where }: { where?: Where }) =>
+    Promise.resolve(SCORES.find((s) => matchesWhere(s, where ?? {})) ?? null),
+  );
+  (prisma.waitlistScore.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { leadId: string } }) =>
+      Promise.resolve(SCORES.find((s) => s.leadId === where.leadId) ?? null),
+  );
+}
+
+function tenant(overrides: Partial<TenantContext>): TenantContext {
+  return {
+    userId: "user_00000000-0000-7000-8000-000000000001" as TenantContext["userId"],
+    organizationId: ORG_SENTINEL as TenantContext["organizationId"],
+    workspaceId: WS_A as TenantContext["workspaceId"],
+    role: "owner",
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  installFixtureMocks();
+});
+
+// ── AC5 — the platform-operator predicate, fail-closed on AILK_OPERATOR_EMAIL ──
+//
+// Sam-disposed 2026-09-02 (PR #4687 security review, High finding): the
+// sentinel-owner predicate alone is no longer sufficient — `kind:"all"`
+// requires an explicit deployment pin. `bindOperatorMembership`
+// (`tenant-context.ts`) TOFU-binds this Membership to whichever caller wins
+// a first-login race when the pin is unset; this surface turns that
+// membership into cross-tenant signup-PII read access, so a deployment must
+// opt in explicitly.
+
+const ORIGINAL_ENV = process.env;
+
+describe("isPlatformOperator / resolveWaitlistReadScope", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.AILK_OPERATOR_EMAIL;
+  });
+  afterAll(() => {
+    process.env = ORIGINAL_ENV;
+  });
+
+  it("AILK_OPERATOR_EMAIL set + sentinel-org owner -> true, scope 'all'", () => {
+    process.env.AILK_OPERATOR_EMAIL = "op@example.com";
+    const t = tenant({ organizationId: ORG_SENTINEL as TenantContext["organizationId"], role: "owner" });
+    expect(isPlatformOperator(t)).toBe(true);
+    expect(resolveWaitlistReadScope(t)).toEqual({ kind: "all" });
+  });
+
+  it("AILK_OPERATOR_EMAIL UNSET + sentinel-org owner -> false, scope 'site' (fail closed)", () => {
+    // AILK_OPERATOR_EMAIL deliberately left unset by beforeEach.
+    const t = tenant({ organizationId: ORG_SENTINEL as TenantContext["organizationId"], role: "owner" });
+    expect(isPlatformOperator(t)).toBe(false);
+    expect(resolveWaitlistReadScope(t)).toEqual({ kind: "site", siteId: WS_A });
+  });
+
+  it("a blank/whitespace-only AILK_OPERATOR_EMAIL is treated as unset (mirrors tenant-context.ts's own trim discipline)", () => {
+    process.env.AILK_OPERATOR_EMAIL = "   ";
+    const t = tenant({ organizationId: ORG_SENTINEL as TenantContext["organizationId"], role: "owner" });
+    expect(isPlatformOperator(t)).toBe(false);
+  });
+
+  it("AILK_OPERATOR_EMAIL set + sentinel-org admin -> false, scope 'site'", () => {
+    process.env.AILK_OPERATOR_EMAIL = "op@example.com";
+    const t = tenant({ organizationId: ORG_SENTINEL as TenantContext["organizationId"], role: "admin" });
+    expect(isPlatformOperator(t)).toBe(false);
+    expect(resolveWaitlistReadScope(t)).toEqual({ kind: "site", siteId: WS_A });
+  });
+
+  it("AILK_OPERATOR_EMAIL set + non-sentinel owner -> false, scope 'site'", () => {
+    process.env.AILK_OPERATOR_EMAIL = "op@example.com";
+    const t = tenant({ organizationId: ORG_B as TenantContext["organizationId"], workspaceId: WS_B as TenantContext["workspaceId"], role: "owner" });
+    expect(isPlatformOperator(t)).toBe(false);
+    expect(resolveWaitlistReadScope(t)).toEqual({ kind: "site", siteId: WS_B });
+  });
+
+  it("false for a member regardless of pin or org (never a platform operator)", () => {
+    process.env.AILK_OPERATOR_EMAIL = "op@example.com";
+    const t = tenant({ organizationId: ORG_SENTINEL as TenantContext["organizationId"], role: "member" });
+    expect(isPlatformOperator(t)).toBe(false);
+  });
+
+  it("the role floor allow-list is exactly owner|admin", () => {
+    expect(WAITLIST_DASHBOARD_ROLES.has("owner")).toBe(true);
+    expect(WAITLIST_DASHBOARD_ROLES.has("admin")).toBe(true);
+    expect(WAITLIST_DASHBOARD_ROLES.has("member")).toBe(false);
+  });
+});
+
+// ── listExperiments — scope + rollup ─────────────────────────────────────────
+
+describe("listExperiments", () => {
+  it("site scope sees only its own site's experiment", async () => {
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+    expect(result.scope).toBe("site");
+    expect(result.experiments.map((e) => e.id)).toEqual([EXP_A]);
+    expect(result.rollup.sites).toBe(1);
+    expect(result.rollup.experiments).toEqual({ total: 1, live: 1, closed: 0, draft: 0 });
+    expect(result.rollup.raw).toBe(4);
+    expect(result.rollup.qualified).toBe(1);
+    expect(result.rollup.qualificationRate).toBeCloseTo(0.25);
+  });
+
+  it("the other site's scope sees only its own experiment, unscored (null rollup)", async () => {
+    const result = await listExperiments({ kind: "site", siteId: WS_B });
+    expect(result.experiments.map((e) => e.id)).toEqual([EXP_B]);
+    expect(result.rollup.experiments).toEqual({ total: 1, live: 0, closed: 0, draft: 1 });
+    expect(result.rollup.raw).toBe(1);
+    expect(result.rollup.qualified).toBeNull();
+    expect(result.rollup.qualificationRate).toBeNull();
+  });
+
+  it("platform-operator scope 'all' sees both sites' experiments; rollup.sites = 2", async () => {
+    const result = await listExperiments({ kind: "all" });
+    expect(result.scope).toBe("all");
+    expect(result.experiments.map((e) => e.id).sort()).toEqual([EXP_A, EXP_B].sort());
+    expect(result.rollup.sites).toBe(2);
+    expect(result.rollup.experiments).toEqual({ total: 2, live: 1, closed: 0, draft: 1 });
+    // Only EXP_A's qualified count is known — EXP_B is unscored (mode
+    // lead-capture) and contributes null, not zero.
+    expect(result.rollup.raw).toBe(5);
+    expect(result.rollup.qualified).toBe(1);
+    expect(result.rollup.qualificationRate).toBeCloseTo(0.2);
+  });
+
+  it("returns an empty, zeroed rollup when scope admits no experiments", async () => {
+    const result = await listExperiments({ kind: "site", siteId: "wksp_00000000-0000-7000-8000-0000000000zz" });
+    expect(result.experiments).toEqual([]);
+    expect(result.rollup).toEqual({
+      experiments: { total: 0, live: 0, closed: 0, draft: 0 },
+      raw: 0,
+      qualified: null,
+      qualificationRate: null,
+      sites: 0,
+    });
+  });
+
+  // Medium finding, PR #4687 security review: a corrupted config on ONE
+  // experiment must not abort the platform operator's whole `all`-scope
+  // list (a cross-tenant availability coupling) — it is skipped, and every
+  // rollup count (total/status/sites/raw/qualified) excludes it.
+  it("skips an experiment with a corrupted config rather than throwing, under kind:'all'", async () => {
+    const corrupt = {
+      id: "wlexp_00000000-0000-7000-8000-0000000000cc",
+      siteId: WS_B,
+      key: "corrupt-exp",
+      mode: "qualifying",
+      status: "live",
+      config: { not: "a valid WaitlistExperimentConfig" },
+      createdAt: new Date("2026-08-03T00:00:00.000Z"),
+      updatedAt: new Date("2026-08-03T00:00:00.000Z"),
+    };
+    EXPERIMENTS.push(corrupt as never);
+    try {
+      const result = await listExperiments({ kind: "all" });
+      expect(result.experiments.map((e) => e.id).sort()).toEqual([EXP_A, EXP_B].sort());
+      // The corrupt row contributes to NEITHER count — same rollup as
+      // without it (the "both sites" test above).
+      expect(result.rollup.experiments).toEqual({ total: 2, live: 1, closed: 0, draft: 1 });
+      expect(result.rollup.sites).toBe(2);
+    } finally {
+      EXPERIMENTS.pop();
+    }
+  });
+
+  it("bounds its Lead/WaitlistScore aggregation reads with a `take` cap (Medium finding, PR #4687)", async () => {
+    await listExperiments({ kind: "all" });
+    const leadCall = (prisma.lead.findMany as jest.Mock).mock.calls[0]?.[0];
+    const scoreCall = (prisma.waitlistScore.findMany as jest.Mock).mock.calls[0]?.[0];
+    expect(typeof leadCall.take).toBe("number");
+    expect(leadCall.take).toBeGreaterThan(0);
+    expect(typeof scoreCall.take).toBe("number");
+    expect(scoreCall.take).toBeGreaterThan(0);
+  });
+
+  // #5107 — without an explicit orderBy, Postgres does not guarantee which
+  // rows survive the `take: MAX_AGGREGATION_ROWS` cap above. Mirrors the
+  // sibling flowSession/flowCheckout reads in this same function (below),
+  // which already carry their own explicit orderBy alongside their take cap.
+  it("orders its Lead/WaitlistScore aggregation reads deterministically (#5107)", async () => {
+    await listExperiments({ kind: "all" });
+    const leadCall = (prisma.lead.findMany as jest.Mock).mock.calls[0]?.[0];
+    const scoreCall = (prisma.waitlistScore.findMany as jest.Mock).mock.calls[0]?.[0];
+    expect(leadCall.orderBy).toEqual({ createdAt: "asc" });
+    expect(scoreCall.orderBy).toEqual({ createdAt: "asc" });
+  });
+});
+
+// ── getExperimentComparison — D4 arithmetic ──────────────────────────────────
+
+describe("getExperimentComparison", () => {
+  it("computes per-waitlist and total metrics per D4, including (direct)/(other) and unscored handling", async () => {
+    const result = await getExperimentComparison({ kind: "all" }, EXP_A);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.experiment.id).toBe(EXP_A);
+    expect(result.value.serviceableExcludes).toEqual(["cold"]);
+
+    const earlyBird = result.value.waitlists.find((w) => w.key === "early_bird");
+    expect(earlyBird).toMatchObject({ raw: 2, qualified: 1, qualificationRate: 0.5, campaign: "eb-campaign" });
+    expect(earlyBird?.byTier.sort((a, b) => a.tier.localeCompare(b.tier))).toEqual([
+      { tier: "cold", count: 1 },
+      { tier: "hot", count: 1 },
+    ]);
+    const ebSources = new Map(earlyBird?.bySource.map((s) => [s.source, s]));
+    expect(ebSources.get("(direct)")).toEqual({ source: "(direct)", raw: 1, qualified: 0, qualificationRate: 0 });
+    expect(ebSources.get("twitter")).toEqual({ source: "twitter", raw: 1, qualified: 1, qualificationRate: 1 });
+
+    const general = result.value.waitlists.find((w) => w.key === "general");
+    // LEAD_3 is unscored -> byTier has no entry for it; qualified counts only
+    // scored, non-excluded leads (zero here — the only score is "cold").
+    expect(general).toMatchObject({ raw: 2, qualified: 0, qualificationRate: 0 });
+
+    const roleDist = general?.distributions.find((d) => d.questionId === "role");
+    const roleOptions = new Map(roleDist?.options.map((o) => [o.value, o]));
+    expect(roleDist?.answered).toBe(2);
+    expect(roleOptions.get("founder")).toEqual({ value: "founder", count: 1, share: 0.5 });
+    // LEAD_4's "weird-value" is not a declared option -> the "(other)" bucket.
+    expect(roleOptions.get("(other)")).toEqual({ value: "(other)", count: 1, share: 0.5 });
+
+    // Total row aggregates over ALL of the experiment's waitlists (D4).
+    expect(result.value.total).toMatchObject({ key: "total", raw: 4, qualified: 1, qualificationRate: 0.25 });
+    const totalRoleDist = result.value.total.distributions.find((d) => d.questionId === "role");
+    expect(totalRoleDist?.answered).toBe(4);
+    const totalRoleOptions = new Map(totalRoleDist?.options.map((o) => [o.value, o]));
+    expect(totalRoleOptions.get("founder")?.count).toBe(2);
+    expect(totalRoleOptions.get("other")?.count).toBe(1);
+    expect(totalRoleOptions.get("(other)")?.count).toBe(1);
+  });
+
+  it("qualified: null and serviceableExcludes: [] for a lead-capture (no scoring) experiment", async () => {
+    const result = await getExperimentComparison({ kind: "all" }, EXP_B);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.serviceableExcludes).toEqual([]);
+    expect(result.value.total.qualified).toBeNull();
+    expect(result.value.total.qualificationRate).toBeNull();
+  });
+
+  it("a foreign experiment id under a site scope is not_found", async () => {
+    const result = await getExperimentComparison({ kind: "site", siteId: WS_B }, EXP_A);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("not_found");
+  });
+
+  it("a missing experiment id under scope 'all' is not_found", async () => {
+    const result = await getExperimentComparison({ kind: "all" }, "wlexp_00000000-0000-7000-8000-00000000dead");
+    expect(result.ok).toBe(false);
+  });
+
+  it("bounds its Lead/WaitlistScore aggregation reads with a `take` cap (Medium finding, PR #4687)", async () => {
+    await getExperimentComparison({ kind: "all" }, EXP_A);
+    const leadCall = (prisma.lead.findMany as jest.Mock).mock.calls[0]?.[0];
+    const scoreCall = (prisma.waitlistScore.findMany as jest.Mock).mock.calls[0]?.[0];
+    expect(typeof leadCall.take).toBe("number");
+    expect(leadCall.take).toBeGreaterThan(0);
+    expect(typeof scoreCall.take).toBe("number");
+    expect(scoreCall.take).toBeGreaterThan(0);
+  });
+
+  // #5107 — same fix as listExperiments's pair above: an explicit orderBy
+  // makes which rows survive the take cap deterministic.
+  it("orders its Lead/WaitlistScore aggregation reads deterministically (#5107)", async () => {
+    await getExperimentComparison({ kind: "all" }, EXP_A);
+    const leadCall = (prisma.lead.findMany as jest.Mock).mock.calls[0]?.[0];
+    const scoreCall = (prisma.waitlistScore.findMany as jest.Mock).mock.calls[0]?.[0];
+    expect(leadCall.orderBy).toEqual({ createdAt: "asc" });
+    expect(scoreCall.orderBy).toEqual({ createdAt: "asc" });
+  });
+});
+
+// ── getSignup — drill-down ────────────────────────────────────────────────────
+
+describe("getSignup", () => {
+  it("returns the scored signup's answers, tier, score, categoryScores, ruleTrace", async () => {
+    const result = await getSignup({ kind: "all" }, EXP_A, LEAD_1);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.waitlistKey).toBe("early_bird");
+    expect(result.value.answers.find((a) => a.questionId === "role")?.value).toBe("founder");
+    expect(result.value.score).toEqual({
+      tier: "hot",
+      score: 5,
+      categoryScores: { total: 5 },
+      ruleTrace: { fired: ["role_pt"] },
+      updatedAt: "2026-08-10T01:00:00.000Z",
+    });
+  });
+
+  it("returns score: null for an unscored signup", async () => {
+    const result = await getSignup({ kind: "all" }, EXP_A, LEAD_3);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.score).toBeNull();
+  });
+
+  it("a foreign lead under a site scope is not_found — no enumeration signal", async () => {
+    const result = await getSignup({ kind: "site", siteId: WS_B }, EXP_B, LEAD_1);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("not_found");
+  });
+
+  it("a lead belonging to a DIFFERENT experiment on the same site is not_found (loaded through the experiment)", async () => {
+    // LEAD_1 exists on site A but under "founder-diagnostic", not under a
+    // second (hypothetical) experiment id on that same site.
+    const result = await getSignup({ kind: "all" }, EXP_B, LEAD_1);
+    expect(result.ok).toBe(false);
+  });
+
+  it("scopes the WaitlistScore read by siteId + experimentKey in the WHERE clause, not a post-filter (Low finding, PR #4687)", async () => {
+    await getSignup({ kind: "all" }, EXP_A, LEAD_1);
+    const call = (prisma.waitlistScore.findFirst as jest.Mock).mock.calls[0]?.[0];
+    expect(call.where).toMatchObject({ leadId: LEAD_1, siteId: WS_A, experimentKey: "founder-diagnostic" });
+  });
+
+  // A lead missing `waitlistKey` is corrupt/anomalous data (server-owned,
+  // written alongside `experimentKey` at completion) — treated as not_found
+  // rather than emitting an out-of-contract empty string (Low finding, PR
+  // #4687 security review).
+  it("treats a signup missing waitlistKey as not_found rather than emitting waitlistKey: ''", async () => {
+    const corruptLead = {
+      id: "lead_00000000-0000-7000-8000-0000000000c1",
+      siteId: WS_A,
+      email: "corrupt@example.com",
+      source: "flow:founder-diagnostic-early",
+      payload: { experimentKey: "founder-diagnostic", role: "founder" }, // no waitlistKey
+      createdAt: new Date("2026-08-15T00:00:00.000Z"),
+    };
+    LEADS.push(corruptLead as never);
+    try {
+      const result = await getSignup({ kind: "all" }, EXP_A, corruptLead.id);
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("not_found");
+    } finally {
+      LEADS.pop();
+    }
+  });
+});
+
+// ── listSignups — pagination ──────────────────────────────────────────────────
+
+describe("listSignups", () => {
+  it("returns the first page newest-first with a nextCursor when more remain", async () => {
+    const result = await listSignups({ kind: "all" }, EXP_A, { limit: 2 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // createdAt desc: LEAD_4 (13th), LEAD_3 (12th) are the newest two.
+    expect(result.value.items.map((i) => i.leadId)).toEqual([LEAD_4, LEAD_3]);
+    expect(result.value.nextCursor).toBe(LEAD_3);
+  });
+
+  it("the second page (via cursor) returns the remaining rows with nextCursor: null", async () => {
+    const result = await listSignups({ kind: "all" }, EXP_A, { limit: 2, cursor: LEAD_3 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items.map((i) => i.leadId)).toEqual([LEAD_2, LEAD_1]);
+    expect(result.value.nextCursor).toBeNull();
+  });
+
+  it("filters by ?waitlist=", async () => {
+    const result = await listSignups({ kind: "all" }, EXP_A, { limit: 50, waitlist: "general" });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.items.map((i) => i.leadId).sort()).toEqual([LEAD_3, LEAD_4].sort());
+  });
+
+  it("carries tier/score from the joined WaitlistScore row, null when absent", async () => {
+    const result = await listSignups({ kind: "all" }, EXP_A, { limit: 50 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const byId = new Map(result.value.items.map((i) => [i.leadId, i]));
+    expect(byId.get(LEAD_1)).toMatchObject({ tier: "hot", score: 5 });
+    expect(byId.get(LEAD_3)).toMatchObject({ tier: null, score: null });
+  });
+
+  it("a foreign experiment id under a site scope is not_found", async () => {
+    const result = await listSignups({ kind: "site", siteId: WS_B }, EXP_A, { limit: 50 });
+    expect(result.ok).toBe(false);
+  });
+
+  // Low finding, PR #4687 security review: a supplied-but-unresolvable
+  // cursor must 400 (invalid_cursor), not silently degrade to page 1.
+  it("a cursor that does not exist at all is invalid_cursor", async () => {
+    const result = await listSignups({ kind: "all" }, EXP_A, {
+      limit: 50,
+      cursor: "lead_00000000-0000-7000-8000-00000000dead",
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("invalid_cursor");
+  });
+
+  it("a cursor belonging to a DIFFERENT experiment on the same site is invalid_cursor", async () => {
+    // LEAD_5 exists on site B under "lead-capture-exp" — not under EXP_A's
+    // "founder-diagnostic", even though both experiments' scope is 'all'.
+    const result = await listSignups({ kind: "all" }, EXP_A, { limit: 50, cursor: LEAD_5 });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("invalid_cursor");
+  });
+
+  it("skips a signup missing waitlistKey rather than emitting waitlistKey: '' (Low finding, PR #4687)", async () => {
+    const corruptLead = {
+      id: "lead_00000000-0000-7000-8000-0000000000c2",
+      siteId: WS_A,
+      email: "corrupt2@example.com",
+      source: "flow:founder-diagnostic-early",
+      payload: { experimentKey: "founder-diagnostic", role: "founder" }, // no waitlistKey
+      createdAt: new Date("2026-08-16T00:00:00.000Z"),
+    };
+    LEADS.push(corruptLead as never);
+    try {
+      const result = await listSignups({ kind: "all" }, EXP_A, { limit: 50 });
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value.items.some((i) => i.leadId === corruptLead.id)).toBe(false);
+      expect(result.value.items.every((i) => i.waitlistKey !== "")).toBe(true);
+    } finally {
+      LEADS.pop();
+    }
+  });
+});
+
+// ── Read-only — no write verb is ever reachable (spec §5.2 AC4) ─────────────
+
+describe("read-only discipline", () => {
+  it("the prisma mock declares no create/update/upsert/delete verb — an accidental call throws, not silently succeeds", () => {
+    for (const model of ["waitlistExperiment", "lead", "waitlistScore"] as const) {
+      for (const verb of ["create", "update", "upsert", "delete", "deleteMany", "updateMany", "createMany"] as const) {
+        expect((prisma[model] as Record<string, unknown>)[verb]).toBeUndefined();
+      }
+    }
+  });
+});
+
+// ── #4839 — per-offer funnel counts for a recommending experiment ───────────
+
+const EXP_R = "wlexp_00000000-0000-7000-8000-0000000000dd"; // recommending, site A
+
+const CONFIG_R = {
+  key: "ailk-reco",
+  mode: "recommending" as const,
+  status: "live" as const,
+  waitlists: [{ key: "main", flowSlug: "ailk-reco" }],
+  questionSet: {
+    version: 1 as const,
+    questions: [
+      {
+        id: "q_team",
+        prompt: en("Team?"),
+        answerType: "single" as const,
+        options: [
+          { value: "solo", label: en("Solo") },
+          { value: "small_team", label: en("Small team") },
+        ],
+      },
+    ],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: { main: { campaign: "reco-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: "stripe-main",
+  offers: [
+    {
+      key: "pro",
+      copy: { name: en("Pro") },
+      price: { kind: "exact" as const, amount: 249, period: "annual" as const },
+      rules: [{ when: { answer: "q_team", eq: "small_team" }, reason: en("Teams need seats.") }],
+    },
+    {
+      key: "starter",
+      copy: { name: en("Starter") },
+      price: { kind: "label" as const, label: en("Free") },
+      rules: [{ when: { answer: "q_team", eq: "solo" }, reason: en("Solo builders start free.") }],
+    },
+  ],
+};
+
+const EXPERIMENT_R = {
+  id: EXP_R,
+  siteId: WS_A,
+  key: CONFIG_R.key,
+  mode: CONFIG_R.mode,
+  status: CONFIG_R.status,
+  config: CONFIG_R,
+  createdAt: new Date("2026-09-01T00:00:00.000Z"),
+  updatedAt: new Date("2026-09-01T00:00:00.000Z"),
+};
+
+const SESSIONS_R = [
+  { siteId: WS_A, flowSlug: "ailk-reco", completedAt: new Date("2026-09-02T00:00:00.000Z"), state: { team: { q_team: "small_team" } } },
+  { siteId: WS_A, flowSlug: "ailk-reco", completedAt: new Date("2026-09-02T01:00:00.000Z"), state: { team: { q_team: "small_team" } } },
+  { siteId: WS_A, flowSlug: "ailk-reco", completedAt: new Date("2026-09-02T02:00:00.000Z"), state: { team: { q_team: "solo" } } },
+  // An incomplete walk and a foreign-site session — never counted.
+  { siteId: WS_A, flowSlug: "ailk-reco", completedAt: null, state: { team: { q_team: "small_team" } } },
+  { siteId: WS_B, flowSlug: "ailk-reco", completedAt: new Date("2026-09-02T03:00:00.000Z"), state: { team: { q_team: "small_team" } } },
+];
+
+const LEAD_R = {
+  id: "lead_00000000-0000-7000-8000-0000000000dd",
+  siteId: WS_A,
+  email: "buyer@example.com",
+  source: "flow:ailk-reco",
+  payload: {
+    experimentKey: "ailk-reco",
+    waitlistKey: "main",
+    q_team: "small_team",
+    recommender: { choice: "save", fits: ["pro"] },
+  },
+  createdAt: new Date("2026-09-02T00:30:00.000Z"),
+};
+
+const CHECKOUTS_R = [
+  { siteId: WS_A, experimentKey: "ailk-reco", offerKey: "pro", status: "completed" },
+  { siteId: WS_A, experimentKey: "ailk-reco", offerKey: "pro", status: "completed" },
+  { siteId: WS_A, experimentKey: "ailk-reco", offerKey: "starter", status: "created" },
+];
+
+function installRecommendingFixtures(): void {
+  EXPERIMENTS.push(EXPERIMENT_R as never);
+  LEADS.push(LEAD_R as never);
+  (prisma.flowSession.findMany as jest.Mock).mockImplementation(
+    ({ where, take }: { where?: Where; take?: number }) => {
+      let rows = SESSIONS_R.filter((r) => {
+        const { completedAt, ...rest } = (where ?? {}) as Where & { completedAt?: { not: null } };
+        if (completedAt && r.completedAt === null) return false;
+        return matchesWhere(r as Row, rest);
+      });
+      if (typeof take === "number") rows = rows.slice(0, take);
+      return Promise.resolve(rows);
+    },
+  );
+  (prisma.flowCheckout.findMany as jest.Mock).mockImplementation(
+    ({ where, take }: { where?: Where; take?: number }) => {
+      let rows = CHECKOUTS_R.filter((r) => matchesWhere(r as Row, where ?? {}));
+      if (typeof take === "number") rows = rows.slice(0, take);
+      return Promise.resolve(rows);
+    },
+  );
+}
+
+function removeRecommendingFixtures(): void {
+  EXPERIMENTS.pop();
+  LEADS.pop();
+}
+
+describe("listExperiments — per-offer funnel counts (#4839)", () => {
+  beforeEach(() => installRecommendingFixtures());
+  afterEach(() => removeRecommendingFixtures());
+
+  it("AC-1: the three counts per offer in register order; a created checkout is not counted; the response parses", async () => {
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+    const reco = result.experiments.find((e) => e.id === EXP_R);
+    expect(reco?.counts.offers).toEqual([
+      { offerKey: "pro", recommended: 2, saved: 1, checkedOut: 2 },
+      { offerKey: "starter", recommended: 1, saved: 0, checkedOut: 0 },
+    ]);
+    expect(() => waitlistDashboardListSchema.parse(result)).not.toThrow();
+    const qualifying = result.experiments.find((e) => e.id === EXP_A);
+    expect(qualifying?.counts).not.toHaveProperty("offers");
+  });
+
+  it("AC-1: a lead-capture experiment in the same list carries no offers key", async () => {
+    const result = await listExperiments({ kind: "all" });
+    const leadCapture = result.experiments.find((e) => e.id === EXP_B);
+    expect(leadCapture?.counts).not.toHaveProperty("offers");
+    expect(result.experiments.find((e) => e.id === EXP_R)?.counts.offers).toHaveLength(2);
+  });
+
+  it("AC-2: exactly one FlowSession read + one FlowCheckout read, scoped under site, capped", async () => {
+    await listExperiments({ kind: "site", siteId: WS_A });
+    expect(prisma.flowSession.findMany).toHaveBeenCalledTimes(1);
+    expect(prisma.flowCheckout.findMany).toHaveBeenCalledTimes(1);
+    const sessionCall = (prisma.flowSession.findMany as jest.Mock).mock.calls[0][0];
+    const checkoutCall = (prisma.flowCheckout.findMany as jest.Mock).mock.calls[0][0];
+    expect(sessionCall.where.siteId).toBe(WS_A);
+    expect(checkoutCall.where.siteId).toBe(WS_A);
+    expect(sessionCall.take).toBe(MAX_AGGREGATION_ROWS);
+    expect(checkoutCall.take).toBe(MAX_AGGREGATION_ROWS);
+    expect(checkoutCall.orderBy).toEqual({ createdAt: "asc" });
+    expect(checkoutCall.where.status).toBe("completed");
+  });
+
+  it("AC-2: the same two reads once under kind:'all', without siteId, even with two recommending experiments", async () => {
+    const second = { ...EXPERIMENT_R, id: "wlexp_00000000-0000-7000-8000-0000000000ee", siteId: WS_B };
+    EXPERIMENTS.push(second as never);
+    try {
+      await listExperiments({ kind: "all" });
+      expect(prisma.flowSession.findMany).toHaveBeenCalledTimes(1);
+      expect(prisma.flowCheckout.findMany).toHaveBeenCalledTimes(1);
+      const sessionCall = (prisma.flowSession.findMany as jest.Mock).mock.calls[0][0];
+      const checkoutCall = (prisma.flowCheckout.findMany as jest.Mock).mock.calls[0][0];
+      expect(sessionCall.where).not.toHaveProperty("siteId");
+      expect(checkoutCall.where).not.toHaveProperty("siteId");
+    } finally {
+      EXPERIMENTS.pop();
+    }
+  });
+
+  it("AC-2: neither read runs when no recommending experiment is in scope", async () => {
+    await listExperiments({ kind: "site", siteId: WS_B });
+    expect(prisma.flowSession.findMany).not.toHaveBeenCalled();
+    expect(prisma.flowCheckout.findMany).not.toHaveBeenCalled();
+  });
+
+  it("AC-4: the rollup and the existing per-experiment counts are unchanged by the funnel", async () => {
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+    // The pre-#4839 fixture's rollup for site A was { raw: 4, qualified: 1,
+    // rate: 0.25 } over EXP_A alone; the recommending experiment adds its one
+    // saved lead to raw (it IS a signup) and nothing else.
+    expect(result.rollup.experiments).toEqual({ total: 2, live: 2, closed: 0, draft: 0 });
+    expect(result.rollup.raw).toBe(5);
+    expect(result.rollup.qualified).toBe(1);
+    expect(result.rollup.qualificationRate).toBeCloseTo(0.2);
+    const qualifying = result.experiments.find((e) => e.id === EXP_A);
+    expect(qualifying?.counts).toEqual({ raw: 4, qualified: 1, qualificationRate: 0.25 });
+  });
+});
+
+// ── #4861 — the read-time recommended count costs the DISTINCT answer sets ───
+//
+// `computeOfferCounts` recomputes the pure `recommend()` for every completed
+// session in scope, up to `MAX_AGGREGATION_ROWS` rows × the register's offers ×
+// their rules, synchronously, on every list read (spec §1's measurement: 232 ms
+// at 4 offers / 459 ms at 8 / 308 ms with scoring, on a 20k-row fixture). Spec
+// D1 memoizes it per call on the session's answers PROJECTED onto the
+// register's declared question ids — sound because
+// `waitlistExperimentConfigSchema` rejects any predicate leaf or scoring point
+// naming an undeclared question (`packages/validation/src/schemas/waitlist.ts:449–452`,
+// `:759–765`), so `recommend()` cannot read a key outside that projection.
+
+const EXP_C = "wlexp_00000000-0000-7000-8000-0000000000cc"; // recommending, site A, cost fixture
+
+const CONFIG_C = {
+  key: "reco-cost",
+  mode: "recommending" as const,
+  status: "live" as const,
+  waitlists: [{ key: "main", flowSlug: "reco-cost" }],
+  questionSet: {
+    version: 1 as const,
+    questions: [
+      // A declared FREE-TEXT question, FIRST in declared order: its answer is
+      // raw visitor input under no charset constraint, so a memo key that
+      // joined `id=value` pairs with a separator could be forged from this box
+      // to impersonate a later question's answer (the third test below).
+      { id: "q_company", prompt: en("Company?"), answerType: "text" as const, minLength: 1 },
+      {
+        id: "q_team",
+        prompt: en("Team?"),
+        answerType: "single" as const,
+        options: [
+          { value: "solo", label: en("Solo") },
+          { value: "small_team", label: en("Small team") },
+          { value: "agency", label: en("Agency") },
+        ],
+      },
+      {
+        id: "q_needs",
+        prompt: en("Needs?"),
+        answerType: "multi" as const,
+        options: [
+          { value: "seo", label: en("SEO") },
+          { value: "leads", label: en("Leads") },
+          { value: "content", label: en("Content") },
+        ],
+      },
+      {
+        id: "q_support",
+        prompt: en("Support?"),
+        answerType: "single" as const,
+        options: [
+          { value: "diy", label: en("DIY") },
+          { value: "guided", label: en("Guided") },
+        ],
+      },
+    ],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+    waitlists: { main: { campaign: "reco-cost-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: "stripe-cost",
+  offers: [
+    {
+      key: "free_oss",
+      copy: { name: en("Free") },
+      price: { kind: "label" as const, label: en("Free") },
+      rules: [{ when: { answer: "q_team", eq: "solo" }, reason: en("Solo builders start free.") }],
+    },
+    {
+      key: "pro",
+      copy: { name: en("Pro") },
+      price: { kind: "exact" as const, amount: 249, period: "annual" as const },
+      rules: [
+        { when: { answer: "q_team", in: ["small_team", "agency"] }, reason: en("Teams need seats.") },
+      ],
+    },
+    {
+      key: "pro_plus",
+      copy: { name: en("Pro Plus") },
+      price: { kind: "exact" as const, amount: 449, period: "monthly" as const },
+      rules: [
+        {
+          when: {
+            allOf: [
+              { answer: "q_team", eq: "agency" },
+              { answer: "q_support", eq: "guided" },
+            ],
+          },
+          reason: en("Agencies want a person to call."),
+        },
+      ],
+    },
+    {
+      key: "launch_service",
+      copy: { name: en("Launch service") },
+      price: { kind: "label" as const, label: en("From $5k") },
+      rules: [
+        {
+          when: {
+            allOf: [
+              { answer: "q_support", eq: "guided" },
+              { answer: "q_needs", includesAny: ["content"] },
+            ],
+          },
+          reason: en("Content plus hand-holding is a service engagement."),
+        },
+      ],
+    },
+  ],
+};
+
+const EXPERIMENT_C = {
+  id: EXP_C,
+  siteId: WS_A,
+  key: CONFIG_C.key,
+  mode: CONFIG_C.mode,
+  status: CONFIG_C.status,
+  config: CONFIG_C,
+  createdAt: new Date("2026-09-03T00:00:00.000Z"),
+  updatedAt: new Date("2026-09-03T00:00:00.000Z"),
+};
+
+const C_TEAMS = ["solo", "small_team", "agency"];
+const C_NEEDS = [["seo"], ["leads"], ["seo", "content"], ["content"]];
+const C_SUPPORT = ["diy", "guided"];
+
+/**
+ * `count` completed sessions cycling through the register's option space — 12
+ * distinct answer sets (lcm(3, 4, 2)) — each carrying a per-session-unique
+ * value under an UNDECLARED key (`email`, as a recommender walk's field step
+ * leaves in `state`). Keying the memo on the raw flattened map would make every
+ * row unique; the D1 projection drops the undeclared key.
+ */
+function costSessions(count: number): Array<{
+  siteId: string;
+  flowSlug: string;
+  completedAt: Date;
+  state: Record<string, Record<string, string | string[]>>;
+}> {
+  const rows = [];
+  for (let i = 0; i < count; i += 1) {
+    rows.push({
+      siteId: WS_A,
+      flowSlug: "reco-cost",
+      completedAt: new Date(1_760_000_000_000 + i),
+      state: {
+        segmentation: {
+          q_team: C_TEAMS[i % 3] as string,
+          q_needs: C_NEEDS[i % 4] as string[],
+          q_support: C_SUPPORT[i % 2] as string,
+        },
+        contact: { email: `visitor-${i}@example.com` },
+      },
+    });
+  }
+  return rows;
+}
+
+/**
+ * The expected per-offer `recommended` counts, re-derived from the fixture's
+ * own answers by reading CONFIG_C's four fit rules directly — never by calling
+ * `recommend()`, so the assertion is independent of the code under test.
+ */
+function expectedRecommended(
+  rows: ReturnType<typeof costSessions>,
+): Record<string, number> {
+  const expected: Record<string, number> = {
+    free_oss: 0,
+    pro: 0,
+    pro_plus: 0,
+    launch_service: 0,
+  };
+  for (const row of rows) {
+    const a = row.state.segmentation as { q_team: string; q_needs: string[]; q_support: string };
+    // CONFIG_C's four fit rules, read straight off the register in its own
+    // order, then capped the way the engine's contract caps them
+    // (`packages/validation/src/schemas/waitlist-recommend.ts:266` — at most
+    // the first three fits are returned).
+    const matched: string[] = [];
+    if (a.q_team === "solo") matched.push("free_oss");
+    if (a.q_team === "small_team" || a.q_team === "agency") matched.push("pro");
+    if (a.q_team === "agency" && a.q_support === "guided") matched.push("pro_plus");
+    if (a.q_support === "guided" && a.q_needs.includes("content")) matched.push("launch_service");
+    for (const key of matched.slice(0, 3)) expected[key] = (expected[key] ?? 0) + 1;
+  }
+  return expected;
+}
+
+describe("listExperiments — recommended-count cost (#4861)", () => {
+  const recommendMock = (
+    jest.requireMock("@working-theory/validation") as { recommend: jest.Mock }
+  ).recommend;
+  const realRecommend = (
+    jest.requireActual("@working-theory/validation") as {
+      recommend: (...args: never[]) => unknown;
+    }
+  ).recommend;
+
+  beforeEach(() => {
+    EXPERIMENTS.push(EXPERIMENT_C as never);
+    recommendMock.mockImplementation(realRecommend);
+    (prisma.flowCheckout.findMany as jest.Mock).mockResolvedValue([]);
+  });
+  afterEach(() => {
+    EXPERIMENTS.pop();
+  });
+
+  it("AC-1: at the 20,000-row cap, recommend() runs once per DISTINCT answer set — and every count is what the rows say", async () => {
+    const rows = costSessions(MAX_AGGREGATION_ROWS);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue(rows);
+
+    const startedAt = Date.now();
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+    const elapsedMs = Date.now() - startedAt;
+
+    // 12 distinct answer sets in 20,000 rows (RED at HEAD: 20,000 calls). The
+    // lower bound keeps the assertion self-proving — a mock that stopped
+    // intercepting would report 0 and pass the ceiling alone.
+    expect(recommendMock.mock.calls.length).toBeGreaterThan(0);
+    expect(recommendMock.mock.calls.length).toBeLessThanOrEqual(32);
+    const expected = expectedRecommended(rows);
+    expect(result.experiments.find((e) => e.id === EXP_C)?.counts.offers).toEqual([
+      { offerKey: "free_oss", recommended: expected.free_oss, saved: 0, checkedOut: 0 },
+      { offerKey: "pro", recommended: expected.pro, saved: 0, checkedOut: 0 },
+      { offerKey: "pro_plus", recommended: expected.pro_plus, saved: 0, checkedOut: 0 },
+      { offerKey: "launch_service", recommended: expected.launch_service, saved: 0, checkedOut: 0 },
+    ]);
+    // A catastrophe ceiling, NOT the budget: the decided budget (≤ 500 ms at
+    // the cap, spec D7) is recorded on #4861 with its measurement, because
+    // wall-clock in CI is not a reliable gate.
+    expect(elapsedMs).toBeLessThan(2_000);
+  }, 60_000);
+
+  it("AC-1: two sessions differing only in an UNDECLARED answer key share one recommend() and both count", async () => {
+    const base = costSessions(1)[0]!;
+    const twin = {
+      ...base,
+      completedAt: new Date(base.completedAt.getTime() + 1),
+      state: {
+        segmentation: { ...base.state.segmentation },
+        contact: { email: "someone-else@example.com" },
+      },
+    };
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([base, twin]);
+
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+
+    expect(recommendMock.mock.calls.length).toBe(1);
+    const offers = result.experiments.find((e) => e.id === EXP_C)?.counts.offers;
+    expect(offers?.find((o) => o.offerKey === "free_oss")?.recommended).toBe(2);
+  });
+
+  it("AC-1: a free-text answer cannot forge another session's answer set into one memo entry", async () => {
+    const at = new Date("2026-09-04T00:00:00.000Z");
+    // Under a delimiter-joined key these two collide: the first session's
+    // company name carries the separator plus a literal `q_team=agency`.
+    const forger = {
+      siteId: WS_A,
+      flowSlug: "reco-cost",
+      completedAt: at,
+      state: { segmentation: { q_company: "Acme\u001eq_team=agency" } },
+    };
+    const genuine = {
+      siteId: WS_A,
+      flowSlug: "reco-cost",
+      completedAt: new Date(at.getTime() + 1),
+      state: { segmentation: { q_company: "Acme", q_team: "agency" } },
+    };
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([forger, genuine]);
+
+    const result = await listExperiments({ kind: "site", siteId: WS_A });
+
+    expect(recommendMock.mock.calls.length).toBe(2);
+    const offers = result.experiments.find((e) => e.id === EXP_C)?.counts.offers;
+    // Only the genuine `agency` answer reaches `pro`; the forger answered no
+    // segmentation question at all and fits nothing.
+    expect(offers?.find((o) => o.offerKey === "pro")?.recommended).toBe(1);
+    expect(offers?.find((o) => o.offerKey === "free_oss")?.recommended).toBe(0);
+  });
+
+  it("AC-3: a flow no register can score costs ONE aggregated warn, not one per row", async () => {
+    const warnSpy = jest.spyOn(logger, "warn").mockImplementation(() => undefined as never);
+    recommendMock.mockImplementation(() => {
+      throw Object.assign(new Error("register drifted"), { name: "WaitlistEvaluationError" });
+    });
+    const rows = costSessions(500);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue(rows);
+
+    try {
+      const result = await listExperiments({ kind: "site", siteId: WS_A });
+
+      const skipWarns = warnSpy.mock.calls.filter(
+        (call) => typeof call[1] === "string" && call[1].includes("[waitlist-dashboard] skipped"),
+      );
+      expect(skipWarns).toHaveLength(1);
+      expect(skipWarns[0]?.[0]).toEqual({
+        siteId: WS_A,
+        experimentKey: "reco-cost",
+        skipped: 500,
+        errName: "WaitlistEvaluationError",
+      });
+      // The failure is memoized too — once per distinct answer set, not per row.
+      expect(recommendMock.mock.calls.length).toBeLessThanOrEqual(32);
+      // A session nothing can score counts nowhere.
+      expect(
+        result.experiments.find((e) => e.id === EXP_C)?.counts.offers?.every((o) => o.recommended === 0),
+      ).toBe(true);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("AC-3: a fully scoreable flow emits no skipped-session warn at all", async () => {
+    const warnSpy = jest.spyOn(logger, "warn").mockImplementation(() => undefined as never);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue(costSessions(60));
+
+    try {
+      await listExperiments({ kind: "site", siteId: WS_A });
+      expect(
+        warnSpy.mock.calls.filter(
+          (call) => typeof call[1] === "string" && call[1].includes("[waitlist-dashboard] skipped"),
+        ),
+      ).toHaveLength(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});