create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,947 @@
+// oss: false
+/**
+ * @file waitlist-dashboard.ts
+ * @description The operator-dashboard READ service (#4665 D2/D3/D4/D5, B0).
+ *
+ * Read-only (`findMany` / `findFirst` / `findUnique` only — no write verb is
+ * reachable from this module, asserted by
+ * `__tests__/waitlist-dashboard.test.ts` and spec §5.2 AC4's
+ * `grep -cE "prisma\.[a-zA-Z]+\.(create|update|upsert|delete|deleteMany|updateMany|createMany)"`
+ * probe). Every query is scoped: `{ siteId }` for `kind: "site"`, nothing
+ * extra for `kind: "all"` (D3) — `scopeWhere` is the single place that
+ * predicate is expressed, so a query missing it is a code-review-visible
+ * omission rather than a silent gap.
+ *
+ * Experiments are addressed by `id` (`wlexp_…`) — never `key`, which is
+ * unique only per `(siteId, key)` and collides under the `all` scope (D3). A
+ * lead is loaded THROUGH its experiment — `findFirst({ id: leadId, siteId:
+ * experiment.siteId, payload: { path: ["experimentKey"], equals:
+ * experiment.key } })` — so a foreign or unrelated lead is `not_found`,
+ * indistinguishable from a missing one (the `tenant.ts` no-enumeration
+ * posture).
+ *
+ * Aggregation runs over ONE scoped `Lead` read (`select: { id, siteId,
+ * email, source, payload, createdAt }`) and ONE scoped `WaitlistScore` read
+ * per experiment (D4) — never a query per question or per source; `list`
+ * runs the same pair ONCE across every returned experiment, grouped in
+ * memory by `${siteId}:${experimentKey}`. For the recommending experiments
+ * in the list it adds ONE scoped `FlowSession` read (completed sessions on
+ * their flow slugs — `recommended` is recomputed from each session's state
+ * with the pure `recommend()`, #4839 D1) and ONE scoped `FlowCheckout` read
+ * (rows at `status: "completed"`, #4839 D3); `saved` comes from the Lead
+ * read already in hand (#4839 D2). Neither read runs when no recommending
+ * experiment is in scope.
+ *
+ * Lives in `apps/api/src/services/` (ADR 0009 D3) — it assembles across the
+ * `auth` `TenantContext` (`tenant-context.ts`) and the `inbox` rows
+ * (`WaitlistExperiment` / `WaitlistScore` / `Lead`).
+ */
+
+import type { Prisma } from "@working-theory/database";
+import { isSentinel } from "@working-theory/ids";
+import { logger } from "@working-theory/observability";
+import {
+  recommend,
+  waitlistExperimentConfigSchema,
+  type WaitlistAnswers,
+  type WaitlistExperimentConfig,
+  type WaitlistExperimentOfferCounts,
+  type WaitlistDashboardList,
+  type WaitlistExperimentComparison,
+  type WaitlistExperimentSummary,
+  type WaitlistMetricRow,
+  type WaitlistSignupDetail,
+  type WaitlistSignupList,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import {
+  computeAnswerDistributions,
+  logAggregationCapHit,
+  MAX_AGGREGATION_ROWS,
+  readPayloadAnswer,
+} from "./answer-distributions.js";
+import type { MembershipRole, TenantContext, TenantResult } from "./tenant-context.js";
+
+// ─── Scope (D2) ──────────────────────────────────────────────────────────────
+
+export type WaitlistReadScope =
+  | { kind: "site"; siteId: string }
+  | { kind: "all" };
+
+/** Reads require `owner` or `admin` in the active organization (D2) — the dashboard exposes signup PII. */
+export const WAITLIST_DASHBOARD_ROLES: ReadonlySet<MembershipRole> = new Set<
+  MembershipRole
+>(["owner", "admin"]);
+
+/**
+ * The platform operator is an `owner`-role member of the sentinel default
+ * Organization (D2) — exactly the identity `bindOperatorMembership` mints
+ * for a single-tenant deployment, and, on a hosted multi-tenant deployment,
+ * the platform's own org owners. Keyed on `isSentinel`, never a literal
+ * (ADR-0031 rule 7).
+ *
+ * Gated by an explicit deployment pin (Sam-disposed 2026-09-02, PR #4687
+ * security review — fail closed): `AILK_OPERATOR_EMAIL` must be SET before
+ * this predicate can ever be true. `bindOperatorMembership`
+ * (`tenant-context.ts`) TOFU-binds the sentinel-owner Membership to whichever
+ * caller wins a first-login race when the pin is unset; before this read
+ * surface existed, winning that race granted scope over only the winner's
+ * own workspace. This surface turns it into cross-tenant signup-PII read
+ * access, so a deployment must opt in explicitly rather than inherit an
+ * unpinned race's outcome. With the pin unset, even a sentinel-org owner
+ * reads at `kind:"site"` scope like any other tenant.
+ */
+export function isPlatformOperator(tenant: TenantContext): boolean {
+  const pinned = process.env.AILK_OPERATOR_EMAIL?.trim();
+  if (!pinned) return false;
+  return isSentinel(tenant.organizationId) && tenant.role === "owner";
+}
+
+/** Owner scope = `siteId == tenant.workspaceId`; platform operator = every site. */
+export function resolveWaitlistReadScope(tenant: TenantContext): WaitlistReadScope {
+  return isPlatformOperator(tenant)
+    ? { kind: "all" }
+    : { kind: "site", siteId: tenant.workspaceId };
+}
+
+function scopeWhere(scope: WaitlistReadScope): { siteId?: string } {
+  return scope.kind === "site" ? { siteId: scope.siteId } : {};
+}
+
+// ─── Row shapes ──────────────────────────────────────────────────────────────
+
+const EXPERIMENT_SELECT = {
+  id: true,
+  siteId: true,
+  key: true,
+  mode: true,
+  status: true,
+  config: true,
+  createdAt: true,
+  updatedAt: true,
+} as const satisfies Prisma.WaitlistExperimentSelect;
+type ExperimentRow = Prisma.WaitlistExperimentGetPayload<{
+  select: typeof EXPERIMENT_SELECT;
+}>;
+
+const LEAD_SELECT = {
+  id: true,
+  siteId: true,
+  email: true,
+  source: true,
+  payload: true,
+  createdAt: true,
+} as const satisfies Prisma.LeadSelect;
+type LeadRow = Prisma.LeadGetPayload<{ select: typeof LEAD_SELECT }>;
+
+const SCORE_SELECT = {
+  leadId: true,
+  siteId: true,
+  experimentKey: true,
+  tier: true,
+  score: true,
+  categoryScores: true,
+  ruleTrace: true,
+  updatedAt: true,
+} as const satisfies Prisma.WaitlistScoreSelect;
+type ScoreRow = Prisma.WaitlistScoreGetPayload<{ select: typeof SCORE_SELECT }>;
+
+const FLOW_SESSION_SELECT = {
+  siteId: true,
+  flowSlug: true,
+  state: true,
+} as const satisfies Prisma.FlowSessionSelect;
+type FlowSessionRow = Prisma.FlowSessionGetPayload<{ select: typeof FLOW_SESSION_SELECT }>;
+
+const FLOW_CHECKOUT_SELECT = {
+  siteId: true,
+  experimentKey: true,
+  offerKey: true,
+} as const satisfies Prisma.FlowCheckoutSelect;
+type FlowCheckoutRow = Prisma.FlowCheckoutGetPayload<{ select: typeof FLOW_CHECKOUT_SELECT }>;
+
+// `MAX_AGGREGATION_ROWS` and `logAggregationCapHit` — the defensive upper
+// bound on an aggregation read (Medium finding, PR #4687 security review) —
+// moved to `./answer-distributions.js` (#4771 D4), which both this module
+// and `flow-aggregate.ts` now import.
+
+// ─── payload / config helpers ────────────────────────────────────────────────
+
+/**
+ * Parse a `WaitlistExperiment.config` JSON column back into its validated
+ * shape, or `undefined` on a parse failure. `config` is written ONLY
+ * through `upsertWaitlistExperiment` (`waitlist-experiments.ts`), which
+ * validates against this same schema before writing — so a parse failure
+ * here signals corrupted row data, not a legitimate read-time possibility.
+ * Mirrors `flow-engine.ts`'s `flowConfigSchema.safeParse` read-back
+ * discipline.
+ */
+function tryParseConfig(
+  raw: unknown,
+): { config: WaitlistExperimentConfig; message?: undefined } | { config?: undefined; message: string } {
+  const parsed = waitlistExperimentConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    return { message: parsed.error.message };
+  }
+  return { config: parsed.data };
+}
+
+/**
+ * Throwing form of `tryParseConfig`, for the single-experiment paths
+ * (`getExperimentComparison` / `getSignup`) where a corrupt row genuinely is
+ * an internal error for that one request — there is no cross-tenant
+ * availability coupling to protect against (the request already named this
+ * one experiment by id). `listExperiments`'s `kind:"all"` loop uses
+ * `tryParseConfig` directly instead, so one tenant's corrupt row can never
+ * abort the platform operator's whole list (Medium finding, PR #4687
+ * security review).
+ */
+function parseConfig(raw: unknown): WaitlistExperimentConfig {
+  const result = tryParseConfig(raw);
+  if (result.config === undefined) {
+    throw new Error(`waitlist-dashboard: experiment config failed to parse: ${result.message}`);
+  }
+  return result.config;
+}
+
+/**
+ * Flatten a completed session's step-keyed `state` into the answer map
+ * `recommend()` takes, keeping only `string | string[]` values. Mirrors
+ * `flow-aggregate.ts`'s module-local `flattenSessionState` (itself a mirror
+ * of `flow-engine.ts`'s) — the "mirrors, not imported" convention those two
+ * already record (#4839 D1).
+ */
+function flattenSessionAnswers(state: unknown): WaitlistAnswers {
+  const answers: WaitlistAnswers = {};
+  if (!state || typeof state !== "object") return answers;
+  for (const stepData of Object.values(state as Record<string, unknown>)) {
+    if (!stepData || typeof stepData !== "object") continue;
+    for (const [name, value] of Object.entries(stepData as Record<string, unknown>)) {
+      if (typeof value === "string") answers[name] = value;
+      else if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        answers[name] = value as string[];
+      }
+    }
+  }
+  return answers;
+}
+
+/**
+ * The memo key for one completed session's answers under `config` (#4861 D1).
+ *
+ * Built from the flattened answers PROJECTED onto the register's declared
+ * question ids, in declared order — never the raw flattened map, which also
+ * carries a walk's field-step values (a visitor's email) and would make almost
+ * every real session's key unique.
+ *
+ * The projection is sound because `recommend()` reads answers only through the
+ * predicate contexts it builds per offer rule and pairing, and through
+ * `evaluateWaitlistScoring` — both address answers by question id, and
+ * `waitlistExperimentConfigSchema` rejects a config whose predicate leaf
+ * (`waitlist.ts:449-452`) or scoring point (`:759-765`) names an undeclared
+ * question. `computeOfferCounts` only ever runs on a config that passed that
+ * parse, so an answer key outside the projection is unreadable by
+ * `recommend()`, and two sessions sharing a signature share a recommendation.
+ *
+ * The key is the JSON encoding of the projected VALUES in declared-id order —
+ * not a delimiter-joined string. Answer values for a `text` question are raw
+ * visitor input under no charset constraint, so any separator character a
+ * joined key used would be forgeable: one visitor typing `q_team=agency` into
+ * a free-text box could otherwise collide with another session that really
+ * answered it. JSON quoting also keeps `"a\u001fb"` distinct from
+ * `["a", "b"]`, which `includesAny` evaluates differently, and an unanswered
+ * question (`null`) distinct from an empty one.
+ */
+function answerSignature(questionIds: readonly string[], answers: WaitlistAnswers): string {
+  return JSON.stringify(questionIds.map((id) => answers[id] ?? null));
+}
+
+/** `payload.recommender` as #4837 D2 writes it — `{ choice, fits }` — or undefined. */
+function readPayloadRecommender(
+  payload: unknown,
+): { choice: string; fits: string[] } | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const value = (payload as Record<string, unknown>)["recommender"];
+  if (typeof value !== "object" || value === null) return undefined;
+  const { choice, fits } = value as Record<string, unknown>;
+  if (typeof choice !== "string" || !Array.isArray(fits)) return undefined;
+  return { choice, fits: fits.filter((f): f is string => typeof f === "string") };
+}
+
+/**
+ * The per-offer funnel for one recommending experiment (#4839 FR2–FR4,
+ * FR6): rows in register `offers[]` order, an all-zero offer still present.
+ */
+function computeOfferCounts(
+  config: WaitlistExperimentConfig,
+  sessions: FlowSessionRow[],
+  leads: LeadRow[],
+  checkouts: FlowCheckoutRow[],
+): WaitlistExperimentOfferCounts[] | undefined {
+  if (config.mode !== "recommending" || !config.offers) return undefined;
+  const counts = new Map<string, WaitlistExperimentOfferCounts>(
+    config.offers.map((o) => [o.key, { offerKey: o.key, recommended: 0, saved: 0, checkedOut: 0 }]),
+  );
+  const slugs = new Set(config.waitlists.map((w) => w.flowSlug));
+  // #4861 D1 — `recommend()` is pure in `(register, answers)` and this loop
+  // always calls it with `flags` defaulted, so the walk costs the DISTINCT
+  // answer sets, not the session rows: at the 20k cap a real register collects
+  // a handful of them. The memo lives for this one call, so an operator's
+  // register edit shows up on the next read with nothing to invalidate (D6).
+  const questionIds = config.questionSet.questions.map((q) => q.id);
+  const fitsBySignature = new Map<string, { fits: string[] } | { errName: string }>();
+  // D5 — one warn per experiment per list call, never one per row: a register
+  // rename that breaks a whole flow used to emit up to MAX_AGGREGATION_ROWS
+  // warn lines from ONE request (PR #4856 round-2 acceptance review).
+  let skipped = 0;
+  let skippedErrName = "UnknownError";
+  let skippedSiteId = "";
+  for (const session of sessions) {
+    if (!slugs.has(session.flowSlug)) continue;
+    // Both helpers are total over a session row (they walk plain JSON and
+    // return), so only `recommend()` needs the try below — the same arm HEAD
+    // guarded.
+    const answers = flattenSessionAnswers(session.state);
+    const signature = answerSignature(questionIds, answers);
+    let entry = fitsBySignature.get(signature);
+    if (entry === undefined) {
+      try {
+        entry = { fits: recommend(config, answers).fits.map((f) => f.offerKey) };
+      } catch (err) {
+        // A session whose state cannot be recommended against the CURRENT
+        // register (a question renamed since it completed) counts nowhere —
+        // memoized like a fit so the throw costs the distinct answer sets too.
+        entry = { errName: err instanceof Error ? err.name : "UnknownError" };
+      }
+      fitsBySignature.set(signature, entry);
+    }
+    if ("errName" in entry) {
+      skipped += 1;
+      skippedErrName = entry.errName;
+      skippedSiteId = session.siteId;
+      continue;
+    }
+    for (const key of entry.fits) {
+      const row = counts.get(key);
+      if (row) row.recommended += 1;
+    }
+  }
+  if (skipped > 0) {
+    // Counts and an error NAME only — never the answers (the logging
+    // discipline the corrupt-config skip already follows).
+    logger.warn(
+      { siteId: skippedSiteId, experimentKey: config.key, skipped, errName: skippedErrName },
+      "[waitlist-dashboard] skipped completed sessions recommend() could not score",
+    );
+  }
+  for (const lead of leads) {
+    const rec = readPayloadRecommender(lead.payload);
+    if (!rec || rec.choice !== "save") continue;
+    for (const key of rec.fits) {
+      const row = counts.get(key);
+      if (row) row.saved += 1;
+    }
+  }
+  for (const checkout of checkouts) {
+    const row = counts.get(checkout.offerKey);
+    if (row) row.checkedOut += 1;
+  }
+  return [...counts.values()];
+}
+
+function readPayloadString(payload: unknown, key: string): string | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const value = (payload as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+// `readPayloadAnswer` moved to `./answer-distributions.js` (#4771 D4),
+// imported above — every call site below is unchanged.
+
+function toSummaryWaitlists(
+  config: WaitlistExperimentConfig,
+): WaitlistExperimentSummary["waitlists"] {
+  return config.waitlists.map((w) => ({
+    key: w.key,
+    flowSlug: w.flowSlug,
+    ...(w.entryPageKey ? { entryPageKey: w.entryPageKey } : {}),
+  }));
+}
+
+// ─── D4 — the metric row (one waitlist, or the total) ───────────────────────
+
+function computeMetricRow(
+  key: WaitlistMetricRow["key"],
+  meta: { campaign?: string | undefined; channels?: string[] | undefined },
+  leads: LeadRow[],
+  scoresByLeadId: Map<string, ScoreRow>,
+  config: WaitlistExperimentConfig,
+): WaitlistMetricRow {
+  const scoring = config.scoring;
+  const serviceableExcludes = new Set(scoring?.serviceableExcludes ?? []);
+  const raw = leads.length;
+
+  // byTier — grouped over the scoped WaitlistScore read (D4).
+  const tierCounts = new Map<string, number>();
+  for (const lead of leads) {
+    const score = scoresByLeadId.get(lead.id);
+    if (!score) continue;
+    tierCounts.set(score.tier, (tierCounts.get(score.tier) ?? 0) + 1);
+  }
+  const byTier = [...tierCounts.entries()].map(([tier, count]) => ({ tier, count }));
+
+  // qualified — null when the experiment carries no scoring register (D4).
+  let qualified: number | null = null;
+  if (scoring) {
+    qualified = 0;
+    for (const [tier, count] of tierCounts) {
+      if (!serviceableExcludes.has(tier)) qualified += count;
+    }
+  }
+  const qualificationRate = qualified === null || raw === 0 ? null : qualified / raw;
+
+  // bySource — grouped by the tracked UTM param NAME (config.tracking.utm.source);
+  // an absent/empty value groups under "(direct)" (D4, Clarifications).
+  const utmParam = config.tracking.utm.source;
+  const bySourceMap = new Map<string, { raw: number; qualified: number }>();
+  for (const lead of leads) {
+    const source = readPayloadString(lead.payload, utmParam) ?? "(direct)";
+    const bucket = bySourceMap.get(source) ?? { raw: 0, qualified: 0 };
+    bucket.raw += 1;
+    const score = scoresByLeadId.get(lead.id);
+    if (scoring && score && !serviceableExcludes.has(score.tier)) {
+      bucket.qualified += 1;
+    }
+    bySourceMap.set(source, bucket);
+  }
+  const bySource = [...bySourceMap.entries()].map(([source, bucket]) => ({
+    source,
+    raw: bucket.raw,
+    qualified: scoring ? bucket.qualified : null,
+    qualificationRate: scoring && bucket.raw > 0 ? bucket.qualified / bucket.raw : null,
+  }));
+
+  // distributions — one per declared question (D4); a value outside the
+  // question's declared options is counted under "(other)" (Clarifications).
+  // Bucketing itself is the shared `computeAnswerDistributions` (#4771 D4) —
+  // this call site only supplies the row → flattened-payload mapping.
+  const distributions = computeAnswerDistributions(
+    config.questionSet.questions,
+    leads.map((lead) => lead.payload),
+  );
+
+  return {
+    key,
+    ...(meta.campaign ? { campaign: meta.campaign } : {}),
+    ...(meta.channels ? { channels: meta.channels } : {}),
+    raw,
+    qualified,
+    qualificationRate,
+    byTier,
+    bySource,
+    distributions,
+  };
+}
+
+function summaryFromRow(
+  row: ExperimentRow,
+  config: WaitlistExperimentConfig,
+  counts: WaitlistExperimentSummary["counts"],
+): WaitlistExperimentSummary {
+  return {
+    id: row.id,
+    siteId: row.siteId,
+    key: row.key,
+    mode: row.mode as WaitlistExperimentSummary["mode"],
+    status: row.status as WaitlistExperimentSummary["status"],
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+    waitlists: toSummaryWaitlists(config),
+    counts,
+  };
+}
+
+// ─── List + rollup (D4, AC1) ─────────────────────────────────────────────────
+
+export async function listExperiments(
+  scope: WaitlistReadScope,
+): Promise<WaitlistDashboardList> {
+  const experiments = await prisma.waitlistExperiment.findMany({
+    where: scopeWhere(scope),
+    orderBy: { createdAt: "desc" },
+    select: EXPERIMENT_SELECT,
+  });
+
+  const emptyRollup: WaitlistDashboardList["rollup"] = {
+    experiments: { total: 0, live: 0, closed: 0, draft: 0 },
+    raw: 0,
+    qualified: null,
+    qualificationRate: null,
+    sites: 0,
+  };
+  if (experiments.length === 0) {
+    return { scope: scope.kind, experiments: [], rollup: emptyRollup };
+  }
+
+  const keys = [...new Set(experiments.map((e) => e.key))];
+  // ONE scoped Lead read + ONE scoped WaitlistScore read across every
+  // returned experiment (D4) — an OR over experimentKey equality is one
+  // query, not one per experiment.
+  const [leads, scores] = await Promise.all([
+    prisma.lead.findMany({
+      where: {
+        ...scopeWhere(scope),
+        OR: keys.map((key) => ({
+          payload: { path: ["experimentKey"], equals: key },
+        })),
+      },
+      // Deterministic read order (#5107) — without an explicit orderBy,
+      // Postgres does not guarantee row order, which rows survive
+      // MAX_AGGREGATION_ROWS is then arbitrary. Mirrors the flowSession/
+      // flowCheckout reads below.
+      orderBy: { createdAt: "asc" },
+      take: MAX_AGGREGATION_ROWS,
+      select: LEAD_SELECT,
+    }),
+    prisma.waitlistScore.findMany({
+      where: { ...scopeWhere(scope), experimentKey: { in: keys } },
+      orderBy: { createdAt: "asc" },
+      take: MAX_AGGREGATION_ROWS,
+      select: SCORE_SELECT,
+    }),
+  ]);
+  logAggregationCapHit("listExperiments.lead", leads.length);
+  logAggregationCapHit("listExperiments.waitlistScore", scores.length);
+
+  // #4839 D1/D3 — ONE FlowSession read + ONE FlowCheckout read across every
+  // recommending experiment in the list; none when there is none. The
+  // register is parsed once more here only to learn the slug set — the
+  // per-row parse below is the authoritative one and skips a corrupt row.
+  const recommending = experiments
+    .map((row) => ({ row, config: tryParseConfig(row.config).config }))
+    .filter((e): e is { row: ExperimentRow; config: WaitlistExperimentConfig } =>
+      e.config?.mode === "recommending" && e.config.offers !== undefined,
+    );
+  let sessions: FlowSessionRow[] = [];
+  let checkouts: FlowCheckoutRow[] = [];
+  if (recommending.length > 0) {
+    const slugs = [...new Set(recommending.flatMap((e) => e.config.waitlists.map((w) => w.flowSlug)))];
+    const recommendingKeys = [...new Set(recommending.map((e) => e.row.key))];
+    [sessions, checkouts] = await Promise.all([
+      prisma.flowSession.findMany({
+        where: { ...scopeWhere(scope), flowSlug: { in: slugs }, completedAt: { not: null } },
+        orderBy: { completedAt: "asc" },
+        take: MAX_AGGREGATION_ROWS,
+        select: FLOW_SESSION_SELECT,
+      }),
+      prisma.flowCheckout.findMany({
+        where: { ...scopeWhere(scope), experimentKey: { in: recommendingKeys }, status: "completed" },
+        orderBy: { createdAt: "asc" },
+        take: MAX_AGGREGATION_ROWS,
+        select: FLOW_CHECKOUT_SELECT,
+      }),
+    ]);
+    logAggregationCapHit("listExperiments.flowSession", sessions.length);
+    logAggregationCapHit("listExperiments.flowCheckout", checkouts.length);
+  }
+  const sessionsBySite = new Map<string, FlowSessionRow[]>();
+  for (const session of sessions) {
+    const bucket = sessionsBySite.get(session.siteId) ?? [];
+    bucket.push(session);
+    sessionsBySite.set(session.siteId, bucket);
+  }
+  const checkoutsByExp = new Map<string, FlowCheckoutRow[]>();
+  for (const checkout of checkouts) {
+    const mapKey = `${checkout.siteId}:${checkout.experimentKey}`;
+    const bucket = checkoutsByExp.get(mapKey) ?? [];
+    bucket.push(checkout);
+    checkoutsByExp.set(mapKey, bucket);
+  }
+
+  const leadsByExp = new Map<string, LeadRow[]>();
+  for (const lead of leads) {
+    const experimentKey = readPayloadString(lead.payload, "experimentKey");
+    if (!experimentKey) continue;
+    const mapKey = `${lead.siteId}:${experimentKey}`;
+    const bucket = leadsByExp.get(mapKey) ?? [];
+    bucket.push(lead);
+    leadsByExp.set(mapKey, bucket);
+  }
+  const scoresByExp = new Map<string, ScoreRow[]>();
+  for (const score of scores) {
+    const mapKey = `${score.siteId}:${score.experimentKey}`;
+    const bucket = scoresByExp.get(mapKey) ?? [];
+    bucket.push(score);
+    scoresByExp.set(mapKey, bucket);
+  }
+
+  const summaries: WaitlistExperimentSummary[] = [];
+  const statusCounts = { live: 0, closed: 0, draft: 0 };
+  const sitesSeen = new Set<string>();
+  let validCount = 0;
+  let rollupRaw = 0;
+  let rollupQualified = 0;
+  let anyQualifiedKnown = false;
+
+  for (const row of experiments) {
+    // A corrupt config on ONE experiment must never abort the platform
+    // operator's WHOLE list under `kind:"all"` (Medium finding, PR #4687
+    // security review) — skip and log rather than throw, BEFORE this row
+    // contributes to any rollup count. Only `{id, siteId, key}` are logged,
+    // never `config` (PII/register boundary, mirrors `waitlist-experiments.ts`'s
+    // own logging discipline).
+    const parsedConfig = tryParseConfig(row.config);
+    if (parsedConfig.config === undefined) {
+      logger.warn(
+        { experimentId: row.id, siteId: row.siteId, key: row.key, reason: parsedConfig.message },
+        "[waitlist-dashboard] skipping experiment — config failed to parse",
+      );
+      continue;
+    }
+    const config = parsedConfig.config;
+
+    validCount += 1;
+    sitesSeen.add(row.siteId);
+    if (row.status === "live") statusCounts.live += 1;
+    else if (row.status === "closed") statusCounts.closed += 1;
+    else if (row.status === "draft") statusCounts.draft += 1;
+
+    const mapKey = `${row.siteId}:${row.key}`;
+    const expLeads = leadsByExp.get(mapKey) ?? [];
+    const expScores = scoresByExp.get(mapKey) ?? [];
+    const scoresByLeadId = new Map(expScores.map((s) => [s.leadId, s]));
+    const metricRow = computeMetricRow("total", {}, expLeads, scoresByLeadId, config);
+
+    rollupRaw += metricRow.raw;
+    if (metricRow.qualified !== null) {
+      rollupQualified += metricRow.qualified;
+      anyQualifiedKnown = true;
+    }
+
+    const offers = computeOfferCounts(
+      config,
+      sessionsBySite.get(row.siteId) ?? [],
+      expLeads,
+      checkoutsByExp.get(mapKey) ?? [],
+    );
+    summaries.push(
+      summaryFromRow(row, config, {
+        raw: metricRow.raw,
+        qualified: metricRow.qualified,
+        qualificationRate: metricRow.qualificationRate,
+        ...(offers !== undefined && { offers }),
+      }),
+    );
+  }
+
+  return {
+    scope: scope.kind,
+    experiments: summaries,
+    rollup: {
+      experiments: { total: validCount, ...statusCounts },
+      raw: rollupRaw,
+      qualified: anyQualifiedKnown ? rollupQualified : null,
+      qualificationRate:
+        anyQualifiedKnown && rollupRaw > 0 ? rollupQualified / rollupRaw : null,
+      sites: sitesSeen.size,
+    },
+  };
+}
+
+// ─── Comparison (D4, AC2) ────────────────────────────────────────────────────
+
+export async function getExperimentComparison(
+  scope: WaitlistReadScope,
+  experimentId: string,
+): Promise<TenantResult<WaitlistExperimentComparison>> {
+  const experiment = await prisma.waitlistExperiment.findFirst({
+    where: { id: experimentId, ...scopeWhere(scope) },
+    select: EXPERIMENT_SELECT,
+  });
+  if (!experiment) {
+    return { ok: false, error: { kind: "not_found", message: "Experiment not found" } };
+  }
+
+  const config = parseConfig(experiment.config);
+
+  const [leads, scores] = await Promise.all([
+    prisma.lead.findMany({
+      where: {
+        siteId: experiment.siteId,
+        payload: { path: ["experimentKey"], equals: experiment.key },
+      },
+      // Deterministic read order (#5107) — see the matching comment on
+      // listExperiments's identical read above.
+      orderBy: { createdAt: "asc" },
+      take: MAX_AGGREGATION_ROWS,
+      select: LEAD_SELECT,
+    }),
+    prisma.waitlistScore.findMany({
+      where: { siteId: experiment.siteId, experimentKey: experiment.key },
+      orderBy: { createdAt: "asc" },
+      take: MAX_AGGREGATION_ROWS,
+      select: SCORE_SELECT,
+    }),
+  ]);
+  logAggregationCapHit("getExperimentComparison.lead", leads.length);
+  logAggregationCapHit("getExperimentComparison.waitlistScore", scores.length);
+  const scoresByLeadId = new Map(scores.map((s) => [s.leadId, s]));
+
+  const waitlistRows = config.waitlists.map((w) => {
+    const waitlistLeads = leads.filter(
+      (lead) => readPayloadString(lead.payload, "waitlistKey") === w.key,
+    );
+    const trackingMeta = config.tracking.waitlists[w.key];
+    return computeMetricRow(
+      w.key,
+      { campaign: trackingMeta?.campaign, channels: trackingMeta?.channels },
+      waitlistLeads,
+      scoresByLeadId,
+      config,
+    );
+  });
+  const totalRow = computeMetricRow("total", {}, leads, scoresByLeadId, config);
+
+  const questions = config.questionSet.questions.map((q) => ({
+    id: q.id,
+    prompt: q.prompt,
+    answerType: q.answerType,
+    ...(q.options
+      ? { options: q.options.map((o) => ({ value: o.value, label: o.label })) }
+      : {}),
+  }));
+
+  const summary = summaryFromRow(experiment, config, {
+    raw: totalRow.raw,
+    qualified: totalRow.qualified,
+    qualificationRate: totalRow.qualificationRate,
+  });
+
+  return {
+    ok: true,
+    value: {
+      experiment: summary,
+      questions,
+      serviceableExcludes: config.scoring?.serviceableExcludes ?? [],
+      waitlists: waitlistRows,
+      total: totalRow,
+    },
+  };
+}
+
+// ─── Signups — paginated list (D7, AC1) ─────────────────────────────────────
+
+/** `listSignups`'s own error kind — `TenantErrorKind` (`tenant-context.ts`)
+ * has no 400-mapped member, and this file does not modify that shared type. */
+export type ListSignupsErrorKind = "not_found" | "invalid_cursor";
+export type ListSignupsResult =
+  | { ok: true; value: WaitlistSignupList }
+  | { ok: false; error: { kind: ListSignupsErrorKind; message: string } };
+
+export async function listSignups(
+  scope: WaitlistReadScope,
+  experimentId: string,
+  params: { waitlist?: string | undefined; cursor?: string | undefined; limit: number },
+): Promise<ListSignupsResult> {
+  const experiment = await prisma.waitlistExperiment.findFirst({
+    where: { id: experimentId, ...scopeWhere(scope) },
+    select: EXPERIMENT_SELECT,
+  });
+  if (!experiment) {
+    return { ok: false, error: { kind: "not_found", message: "Experiment not found" } };
+  }
+
+  let cursorLead: { createdAt: Date; id: string } | undefined;
+  if (params.cursor) {
+    // Scoped to THIS experiment (siteId + experimentKey), not just siteId —
+    // a cursor belonging to a different experiment on the same site is
+    // exactly as invalid as one that does not exist (Low finding, PR #4687
+    // security review: a supplied-but-unresolvable cursor must 400, not
+    // silently degrade to page 1).
+    cursorLead =
+      (await prisma.lead.findFirst({
+        where: {
+          id: params.cursor,
+          siteId: experiment.siteId,
+          payload: { path: ["experimentKey"], equals: experiment.key },
+        },
+        select: { id: true, createdAt: true },
+      })) ?? undefined;
+    if (!cursorLead) {
+      return {
+        ok: false,
+        error: { kind: "invalid_cursor", message: "cursor does not resolve within this experiment" },
+      };
+    }
+  }
+
+  const pathFilters: Prisma.LeadWhereInput[] = [
+    { payload: { path: ["experimentKey"], equals: experiment.key } },
+  ];
+  if (params.waitlist) {
+    pathFilters.push({ payload: { path: ["waitlistKey"], equals: params.waitlist } });
+  }
+
+  const rows = await prisma.lead.findMany({
+    where: {
+      siteId: experiment.siteId,
+      AND: [
+        ...pathFilters,
+        ...(cursorLead
+          ? [
+              {
+                OR: [
+                  { createdAt: { lt: cursorLead.createdAt } },
+                  {
+                    createdAt: cursorLead.createdAt,
+                    id: { lt: cursorLead.id },
+                  },
+                ],
+              },
+            ]
+          : []),
+      ],
+    },
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    take: params.limit + 1,
+    select: LEAD_SELECT,
+  });
+
+  const hasMore = rows.length > params.limit;
+  const page = hasMore ? rows.slice(0, params.limit) : rows;
+  const leadIds = page.map((r) => r.id);
+  const scores =
+    leadIds.length > 0
+      ? await prisma.waitlistScore.findMany({
+          // `siteId` is included even though `leadIds` are already scope-derived
+          // (D3: scope is a parameter of EVERY query — the invariant holds by
+          // construction here too, matching `getSignup`'s defensive re-check).
+          where: { leadId: { in: leadIds }, siteId: experiment.siteId },
+          select: SCORE_SELECT,
+        })
+      : [];
+  const scoreByLeadId = new Map(scores.map((s) => [s.leadId, s]));
+
+  // A lead missing `waitlistKey` is corrupt/anomalous data (same posture as
+  // the corrupt-config skip above) — skipped rather than emitted with an
+  // out-of-contract empty string (Low finding, PR #4687 security review).
+  // `nextCursor`/`hasMore` are computed from `page` BEFORE this filter (the
+  // true pagination boundary), so a skip here never desyncs pagination.
+  const items: WaitlistSignupList["items"] = [];
+  for (const lead of page) {
+    const waitlistKey = readPayloadString(lead.payload, "waitlistKey");
+    if (!waitlistKey) {
+      logger.warn(
+        { experimentId: experiment.id, siteId: experiment.siteId, leadId: lead.id },
+        "[waitlist-dashboard] skipping signup — missing waitlistKey",
+      );
+      continue;
+    }
+    const score = scoreByLeadId.get(lead.id);
+    items.push({
+      leadId: lead.id,
+      waitlistKey,
+      email: lead.email,
+      createdAt: lead.createdAt.toISOString(),
+      source: lead.source,
+      tier: score?.tier ?? null,
+      score: score?.score ?? null,
+    });
+  }
+
+  return {
+    ok: true,
+    value: {
+      experimentId: experiment.id,
+      items,
+      nextCursor: hasMore ? (page[page.length - 1]?.id ?? null) : null,
+    },
+  };
+}
+
+// ─── Signup drill-down (D7, AC3) ─────────────────────────────────────────────
+
+export async function getSignup(
+  scope: WaitlistReadScope,
+  experimentId: string,
+  leadId: string,
+): Promise<TenantResult<WaitlistSignupDetail>> {
+  const experiment = await prisma.waitlistExperiment.findFirst({
+    where: { id: experimentId, ...scopeWhere(scope) },
+    select: EXPERIMENT_SELECT,
+  });
+  if (!experiment) {
+    return { ok: false, error: { kind: "not_found", message: "Experiment not found" } };
+  }
+
+  // Loaded THROUGH its experiment (D3) — a foreign or unrelated lead is
+  // not_found, indistinguishable from a missing one.
+  const lead = await prisma.lead.findFirst({
+    where: {
+      id: leadId,
+      siteId: experiment.siteId,
+      payload: { path: ["experimentKey"], equals: experiment.key },
+    },
+    select: LEAD_SELECT,
+  });
+  if (!lead) {
+    return { ok: false, error: { kind: "not_found", message: "Signup not found" } };
+  }
+
+  const config = parseConfig(experiment.config);
+  // `waitlistKey` is server-written LAST alongside `experimentKey`
+  // (flow-engine.ts D4) — a Lead whose payload carries `experimentKey` but
+  // no `waitlistKey` is corrupt/anomalous data, not a legitimate state.
+  // Treated as not_found rather than emitting an out-of-contract empty
+  // string (`waitlistKey` is a non-empty `flowIdentifierSchema` on the wire,
+  // Low finding, PR #4687 security review) — the same posture the corrupt
+  // WaitlistExperiment.config skip already applies one level up.
+  const waitlistKey = readPayloadString(lead.payload, "waitlistKey");
+  if (!waitlistKey) {
+    logger.warn(
+      { experimentId: experiment.id, siteId: experiment.siteId, leadId: lead.id },
+      "[waitlist-dashboard] signup missing waitlistKey — treating as not_found",
+    );
+    return { ok: false, error: { kind: "not_found", message: "Signup not found" } };
+  }
+
+  const answers = config.questionSet.questions.map((q) => ({
+    questionId: q.id,
+    prompt: q.prompt,
+    value: readPayloadAnswer(lead.payload, q.id) ?? null,
+  }));
+
+  // `leadId` is `@@unique`, so `findFirst` with the scope predicates ANDed in
+  // still resolves at most one row — the scope is now a parameter of this
+  // query (D3), not a post-filter (Low finding, PR #4687 security review).
+  const scoreRow = await prisma.waitlistScore.findFirst({
+    where: { leadId: lead.id, siteId: experiment.siteId, experimentKey: experiment.key },
+    select: SCORE_SELECT,
+  });
+  const score = scoreRow
+    ? {
+        tier: scoreRow.tier,
+        score: scoreRow.score,
+        categoryScores: scoreRow.categoryScores as Record<string, number>,
+        ruleTrace: scoreRow.ruleTrace,
+        updatedAt: scoreRow.updatedAt.toISOString(),
+      }
+    : null;
+
+  return {
+    ok: true,
+    value: {
+      leadId: lead.id,
+      experimentId: experiment.id,
+      experimentKey: experiment.key,
+      waitlistKey,
+      email: lead.email,
+      createdAt: lead.createdAt.toISOString(),
+      source: lead.source,
+      answers,
+      score,
+    },
+  };
+}