create-ailk 0.1.1 → 0.3.0

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

@@ -1,947 +0,0 @@
-// 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,
-    },
-  };
-}