@pithy-sh/testers 0.1.0

package/src/projection/trend.ts

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { TrendDirection } from "../data/enums";
+
+/**
+ * The trend: which way a cohort is heading, and one sentence saying why.
+ *
+ * **A published rule, not a fit.** Three inputs, evaluated in a fixed order, with the thresholds
+ * written down. A developer looking at a red arrow can work out exactly what produced it, which is the
+ * whole difference between a signal they will act on and one they will learn to ignore.
+ *
+ * **The deltas are precomputed onto the snapshot row rather than derived on read.** That is what lets a
+ * summary card render from one row — no client-side series arithmetic, and therefore no way for the
+ * card and the chart to disagree about the same cohort. It also means the delta recorded on a day is
+ * the delta as it was computed on that day, which survives a later correction to history.
+ *
+ * **`fragile` is deliberately not a direction.** A cohort can be improving and fragile at the same
+ * time — three new opt-ins this week and still sitting at exactly twelve with someone dark for nine
+ * days — and collapsing that into one enum would lose whichever of the two is more urgent. It gets its
+ * own boolean and earns its own badge.
+ */
+
+/** Fewer snapshots than this and there is no trend, only noise. */
+const MIN_SNAPSHOTS_FOR_TREND = 3;
+
+/** A forecast move of at least this much over a week is a direction rather than a wobble. */
+const SIGNIFICANT_PROBABILITY_DELTA = 0.05;
+
+/** One earlier snapshot, reduced to what the trend rule reads. */
+export interface TrendPoint {
+  readonly estimatedOptedInCount: number;
+  readonly activeCount: number;
+  readonly successProbability: number | null;
+}
+
+/** Today's position, plus the history to measure it against. */
+export interface TrendInput {
+  readonly today: TrendPoint;
+  /** Yesterday's snapshot, or null if there is none. */
+  readonly yesterday: TrendPoint | null;
+  /** The snapshot from seven days ago, or null if the cohort is younger than that. */
+  readonly weekAgo: TrendPoint | null;
+  /** How many snapshots exist in total, including today's. */
+  readonly snapshotCount: number;
+  /** Whether the cohort is at target with zero headroom right now. */
+  readonly atTargetWithNoHeadroom: boolean;
+  /** How many currently opted-in testers are at-risk or critical. */
+  readonly weakMemberCount: number;
+  /** How many testers went dark in the last week — for the sentence, not the direction. */
+  readonly newlyDarkCount: number;
+}
+
+/** The computed trend: the deltas, the direction, the fragility flag, and the sentence. */
+export interface Trend {
+  readonly optedInDelta1d: number | null;
+  readonly optedInDelta7d: number | null;
+  readonly activeDelta7d: number | null;
+  readonly successProbabilityDelta1d: number | null;
+  readonly successProbabilityDelta7d: number | null;
+  readonly direction: TrendDirection;
+  readonly fragile: boolean;
+  /** One brand-voice sentence explaining the direction, for rendering beside the arrow. */
+  readonly reason: string;
+}
+
+/** A difference, or null when either end is missing. */
+function delta(current: number | null, previous: number | null | undefined): number | null {
+  if (current === null || previous === null || previous === undefined) return null;
+  return current - previous;
+}
+
+/** Compute the trend. */
+export function computeTrend(input: TrendInput): Trend {
+  const optedInDelta1d = input.yesterday
+    ? input.today.estimatedOptedInCount - input.yesterday.estimatedOptedInCount
+    : null;
+  const optedInDelta7d = input.weekAgo ? input.today.estimatedOptedInCount - input.weekAgo.estimatedOptedInCount : null;
+  const activeDelta7d = input.weekAgo ? input.today.activeCount - input.weekAgo.activeCount : null;
+  const probabilityDelta1d = delta(input.today.successProbability, input.yesterday?.successProbability);
+  const probabilityDelta7d = delta(input.today.successProbability, input.weekAgo?.successProbability);
+
+  const fragile = input.atTargetWithNoHeadroom && input.weakMemberCount > 0;
+
+  // The week is the preferred window, and yesterday is the fallback rather than an addition. A cohort
+  // with three to seven snapshots has no `weekAgo` at all — the lookup is an exact-day match — so the
+  // weekly deltas are null through the whole first week, and a rule reading only them had nothing to
+  // read for half the window it exists to watch.
+  const window: TrendWindow =
+    optedInDelta7d !== null || probabilityDelta7d !== null
+      ? { span: "week", optedIn: optedInDelta7d, probability: probabilityDelta7d }
+      : { span: "day", optedIn: optedInDelta1d, probability: probabilityDelta1d };
+
+  const { direction, reason } = classify(input, window, fragile);
+
+  return {
+    optedInDelta1d,
+    optedInDelta7d,
+    activeDelta7d,
+    successProbabilityDelta1d: probabilityDelta1d,
+    successProbabilityDelta7d: probabilityDelta7d,
+    direction,
+    fragile,
+    reason,
+  };
+}
+
+/** Whichever comparison the rule had data for, and how to say it. */
+interface TrendWindow {
+  readonly span: "week" | "day";
+  readonly optedIn: number | null;
+  readonly probability: number | null;
+}
+
+/** The rule itself, evaluated in order, with the sentence each branch produces. */
+function classify(
+  input: TrendInput,
+  window: TrendWindow,
+  fragile: boolean,
+): { direction: TrendDirection; reason: string } {
+  // Two points make a straight line through noise. Say so rather than draw it.
+  if (input.snapshotCount < MIN_SNAPSHOTS_FOR_TREND) {
+    return { direction: "unknown", reason: "Not enough history yet." };
+  }
+
+  // Neither window had an end to measure against. `steady` is a claim, and the deltas go null
+  // specifically so that absent data never renders as "no change" — the direction has to obey the same
+  // rule the numbers do.
+  if (window.optedIn === null && window.probability === null) {
+    return { direction: "unknown", reason: "Not enough history yet." };
+  }
+
+  const since = window.span === "week" ? "this week" : "since yesterday";
+  const optedInDelta7d = window.optedIn;
+  const probabilityDelta7d = window.probability;
+
+  const losingTesters = optedInDelta7d !== null && optedInDelta7d < 0;
+  const losingConfidence = probabilityDelta7d !== null && probabilityDelta7d <= -SIGNIFICANT_PROBABILITY_DELTA;
+
+  if (losingTesters || losingConfidence) {
+    if (losingTesters) {
+      const lost = Math.abs(optedInDelta7d as number);
+      return {
+        direction: "declining",
+        reason: lost === 1 ? `One tester dropped out ${since}.` : `${lost} testers dropped out ${since}.`,
+      };
+    }
+    if (input.newlyDarkCount > 0) {
+      // Not `since` — this one is not a windowed delta. `newlyDark` counts testers whose darkness is
+      // *currently* between three and seven days, measured against now alone, so every one of them
+      // went quiet at least three days ago. Saying "since yesterday" about that would be false by
+      // construction on any cohort young enough to take the daily window.
+      return {
+        direction: "declining",
+        reason:
+          input.newlyDarkCount === 1
+            ? "One tester has gone quiet this week."
+            : `${input.newlyDarkCount} testers have gone quiet this week.`,
+      };
+    }
+    return { direction: "declining", reason: `The forecast has fallen ${since}.` };
+  }
+
+  const gainingTesters = optedInDelta7d !== null && optedInDelta7d > 0;
+  const gainingConfidence = probabilityDelta7d !== null && probabilityDelta7d >= SIGNIFICANT_PROBABILITY_DELTA;
+
+  if (gainingTesters || gainingConfidence) {
+    if (gainingTesters) {
+      const gained = optedInDelta7d as number;
+      return {
+        direction: "improving",
+        reason: gained === 1 ? `One more opt-in ${since}.` : `${gained} more opt-ins ${since}.`,
+      };
+    }
+    return { direction: "improving", reason: `The forecast has risen ${since}.` };
+  }
+
+  // Steady is the residual, and it still has two flavours worth distinguishing: holding comfortably,
+  // and holding with nothing to spare. The second reads as fine on a count and is one lapse from a
+  // reset, which is exactly the state a developer needs told rather than left to infer.
+  if (fragile) {
+    return { direction: "steady", reason: "Holding at target. No headroom." };
+  }
+  return { direction: "steady", reason: `Steady ${since}.` };
+}

package/src/provision/provisionTesters.ts

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { TESTERS_CAPABILITY } from "../workflows/specs";
+
+/**
+ * The provisioning orchestration for the testers capability — the live counterpart to
+ * `pithy add testers`'s config wiring.
+ *
+ * The split is the same one every capability makes, and worth restating because the two commands look
+ * like one. `pithy add` writes *bindings*: it installs the package, adds `testers()` to
+ * `pithy.config.ts`, and puts a `DB` entry in `wrangler.jsonc`. It touches no Cloudflare account, so
+ * adding a capability stays something you can do offline, in CI, or without credentials. This command
+ * stands up the one thing those bindings point at: the prebuilt worker that hosts the daily pass.
+ *
+ * The `TESTERS_DAILY` Workflow binding belongs to this side of the split for a mechanical reason.
+ * Wrangler requires a `name` and a `class_name` on every `workflows` entry, and the deployed name is
+ * per environment — so `add` writes none, because a partial entry stops wrangler loading the config at
+ * all, and the CLI writes the complete entry here once the host exists.
+ *
+ * **This provisioner is unusually small, and the reason is worth stating.** There is no bucket to
+ * create, no index, and — since the confirmation token became a random value on the tester's own row
+ * rather than a signature — no secret to write and no master key to bind. What is left is a template,
+ * a deploy, and a binding. A capability that needs less provisioning is a capability an adopter is more
+ * likely to actually finish setting up.
+ *
+ * The live Cloudflare/wrangler steps sit behind the {@link TestersProvisioner} seam, so the
+ * orchestration — order, idempotency, per-environment fan-out — is unit-tested with a fake that records
+ * its call order, and no account. **Every step is idempotent**: the deploy overwrites, and the binding
+ * write is a find-or-append. Re-running is a no-op.
+ *
+ * **What it deliberately does not do.** It does not run the pass. A provision that also fired the daily
+ * job would mail an adopter's testers as a side effect of a deployment command, which is the kind of
+ * surprise that costs a sending domain its reputation. `pithy testers run` is the explicit way.
+ */
+
+/**
+ * The deployed daily-pass worker name for a project's environment — also its resolved config's basename.
+ *
+ * Through core's naming facade under the **`worker`** namespace: the kind of thing carries the cap, so
+ * this cannot be measured against some other namespace's number, and the environment is validated here
+ * rather than at the deploy that would have used it.
+ */
+export function testersWorkerName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).worker(TESTERS_CAPABILITY);
+}
+
+/**
+ * The live Cloudflare/wrangler seam. Each step must be idempotent.
+ *
+ * Narrow on purpose: everything a fake needs to stand in for is an account check and a deploy, which is
+ * what makes the orchestration testable without a Cloudflare account.
+ */
+export interface TestersProvisioner {
+  /** Fail before the first deploy if the account cannot host a Workflow at all. */
+  preflight(): Promise<void>;
+  /** Resolve the committed template for this environment and `wrangler deploy` it. */
+  deployWorker(env: ManagedEnvironment): Promise<void>;
+}
+
+/** The live seam for taking a deployed host back down. */
+export interface TestersDeprovisioner {
+  /** Delete this environment's daily-pass worker. Absent is success — teardown is idempotent. */
+  deleteWorker(env: ManagedEnvironment): Promise<void>;
+}
+
+/** What one provisioning run did, per environment, for the command to report. */
+export interface TestersProvisionResult {
+  readonly env: ManagedEnvironment;
+  readonly worker: string;
+}
+
+/**
+ * Provision the daily-pass host across every managed environment.
+ *
+ * Preflight runs once, before any deploy. Failing there means failing before one environment is half
+ * provisioned rather than part way through the fan-out — the state that is hardest to reason about and
+ * hardest to recover from.
+ */
+export async function provisionTesters(
+  provisioner: TestersProvisioner,
+  project: string,
+  environments: readonly ManagedEnvironment[],
+): Promise<TestersProvisionResult[]> {
+  await provisioner.preflight();
+
+  const results: TestersProvisionResult[] = [];
+  for (const env of environments) {
+    await provisioner.deployWorker(env);
+    results.push({ env, worker: testersWorkerName(project, env) });
+  }
+  return results;
+}
+
+/** Take every environment's host back down. Idempotent: a worker that is already gone is success. */
+export async function deprovisionTesters(
+  deprovisioner: TestersDeprovisioner,
+  project: string,
+  environments: readonly ManagedEnvironment[],
+): Promise<TestersProvisionResult[]> {
+  const results: TestersProvisionResult[] = [];
+  for (const env of environments) {
+    await deprovisioner.deleteWorker(env);
+    results.push({ env, worker: testersWorkerName(project, env) });
+  }
+  return results;
+}

package/src/provision/resolveTestersConfig.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import { suppressionDatabaseName } from "@pithy-sh/email/src/provision/provisionEmail";
+import { emailMessagesVars } from "@pithy-sh/email/src/provision/resolveEmailConfig";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { TestersConfig } from "../config/config";
+import { TESTERS_CAPABILITY, testersWorkflowRegistry } from "../workflows/specs";
+
+/**
+ * Resolve the daily-pass worker's committed `wrangler.jsonc` template into one environment's standalone
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
+ * binding names — stays as the template committed it.
+ *
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics. What this file adds is the
+ * one thing the generic resolver deliberately does not do: it **rewrites `workflows` and
+ * `triggers.crons` from the capability's own specs** rather than from the template's block. The
+ * template carries both so it reads as a complete, deployable config, but `workflows/specs.ts` is the
+ * single source of the binding name, the class name, and the schedule — so moving the pass off 05:00
+ * is a one-line spec edit, not a spec edit plus a JSONC edit that nothing checks agree.
+ *
+ * Pure: the caller parses the template and writes the result.
+ */
+
+/** The sending identity the host needs to enqueue mail, copied from the email capability's config. */
+export interface TestersEmailIdentity {
+  /** The from address. Must be on a domain onboarded to Cloudflare Email Service. */
+  readonly fromAddress: string;
+  /** The from display name recipients see. */
+  readonly fromName: string;
+  /** The resolved email theme, serialized into the host's `EMAIL_THEME` var. */
+  readonly theme: unknown;
+  /**
+   * The project's email catalogs, from the composed email capability's `hostCatalogs()` — serialized
+   * into the host's `EMAIL_MESSAGES` var.
+   *
+   * The same journey the theme makes, and it has to be: this host composes nothing. `nudge/enqueueSeam.ts`
+   * reads `env.EMAIL_MESSAGES` "exactly as the email host worker carries them", and until this field
+   * existed nothing wrote it — so the nudge shell was the kit's English however many languages the
+   * project spoke, which is the pithy-sh/pithy#441 defect surviving on the second Worker that reads
+   * the var.
+   *
+   * The **shell** is what it moves — the document's `lang` and `dir`, the footer's opt-out word. A
+   * nudge's own words are the adopter's copy, supplied per message and never in a catalog.
+   *
+   * **Required, and `{}` is the way to say "none".** `CloudflareEmailProvisionerOptions.messages` is
+   * required for the same reason and it is the same reason twice: a provisioner that forgot the
+   * catalogs is exactly what left this var written by nobody, and a field carrying a default cannot be
+   * forgotten out loud. Empty writes no var at all, which is the host's own spelling of "the English I
+   * bundle" and what a project serving one language wants.
+   */
+  readonly messages: LocaleCatalogs;
+}
+
+/** The resolved ids and per-env values for one environment's daily-pass deploy. */
+export interface TestersConfigParams {
+  /**
+   * The project name — the `<project>` segment the deployed host, its daily Workflow, and the
+   * suppression database name all lead with. The root `pithy.config.ts` `name`, resolved by
+   * `requireProjectName` and never guessed.
+   */
+  readonly project: string;
+  /** The target environment. */
+  readonly env: ManagedEnvironment;
+  /** The app database id — where the `pithy_testers_*`, `pithy_auth_*` and `pithy_email_jobs` tables live. */
+  readonly appDatabaseId: string;
+  /**
+   * The project's email-suppression database id.
+   *
+   * Shared across environments rather than per environment, matching how `@pithy-sh/email` provisions
+   * it: an unsubscribe in prod must stop staging too, so every environment's host binds the same
+   * database. Shared across *projects* it is not — the name carries the project, so one product's
+   * opt-out list can no longer suppress another's transactional mail.
+   */
+  readonly suppressionDatabaseId: string;
+  /** The app's resolved testers config — serialized into the host's `TESTERS_CONFIG` var. */
+  readonly testersConfig: TestersConfig;
+  /**
+   * The sending identity, or undefined when the project composes no email capability.
+   *
+   * Undefined is a legitimate state rather than an error: the pass still advances roster state and
+   * writes its snapshot, it simply sends nothing. A default address would be worse than an absent one —
+   * mail from a domain the adopter's DKIM does not cover trains recipients' providers to distrust the
+   * real domain, which is the opposite of what this capability is for.
+   */
+  readonly email: TestersEmailIdentity | undefined;
+}
+
+/** Fill the template for one environment. */
+export function resolveTestersConfig(
+  template: WorkflowHostTemplate,
+  params: TestersConfigParams,
+): WorkflowHostTemplate {
+  const { project, env, appDatabaseId, suppressionDatabaseId, testersConfig, email } = params;
+
+  // Derived before the resolve: `resolveWorkflowHost` refuses a template that declares `workflows`
+  // without them, because the only name it could invent unaided is one a second project would overwrite.
+  const derived = hostWorkflowsFor(testersWorkflowRegistry, { project, capability: TESTERS_CAPABILITY, env });
+
+  const resolved = resolveWorkflowHost(template, {
+    project,
+    capability: TESTERS_CAPABILITY,
+    env,
+    databaseIds: { DB: appDatabaseId, EMAIL_SUPPRESSIONS: suppressionDatabaseId },
+    // The suppression database is email's, and its name now carries the project. Left alone, the
+    // template would print `pithy-email-suppressions` — a name no account holds.
+    databaseNames: { EMAIL_SUPPRESSIONS: suppressionDatabaseName(project) },
+    workflows: derived.workflows,
+    vars: {
+      TESTERS_CONFIG: JSON.stringify(testersConfig),
+      // Only set when there is an identity to set. The removal below is the other half — see it for why
+      // omitting the key is not the same as not writing one.
+      ...(email
+        ? {
+            EMAIL_FROM_ADDRESS: email.fromAddress,
+            EMAIL_FROM_NAME: email.fromName,
+            EMAIL_THEME: JSON.stringify(email.theme),
+            // Through `@pithy-sh/email`'s own composer, not a local `JSON.stringify`: it is the same
+            // var against the same 5 KB Cloudflare ceiling on the same account, and error 10054 in
+            // the middle of a provision run is a wrangler exit nobody can act on. One refusal, one
+            // action line, for both hosts.
+            ...emailMessagesVars(email.messages),
+          }
+        : {}),
+    },
+  });
+
+  // The template declares the three `EMAIL_*` vars as `<filled-at-provision>` so it reads as a complete
+  // config, and `resolveWorkflowHost` merges rather than replaces — so *not writing* them leaves the
+  // placeholders in place rather than leaving them absent. The worker's `if (!env.EMAIL_FROM_ADDRESS)`
+  // guard reads a placeholder as an identity, and the failure lands one step later, inside a
+  // `JSON.parse` of `EMAIL_THEME`, in a catch that swallows it. A project that composes no email
+  // capability would deploy a host that looks configured to send and silently never does.
+  if (!email) {
+    for (const key of ["EMAIL_FROM_ADDRESS", "EMAIL_FROM_NAME", "EMAIL_THEME"]) delete resolved.vars?.[key];
+  }
+
+  // The configured hour, applied to the schedule the spec declares. The spec owns *that there is a
+  // daily cron and when it sits by default*; the adopter owns which hour it fires, and until this line
+  // existed `snapshotHourUtc` was a fully described, bounded, defaulted knob that nothing read — so
+  // setting it to 9 because 05:00 collided with their own nightly job changed nothing, silently.
+  const crons = derived.crons.map((cron) => {
+    const fields = cron.split(" ");
+    fields[1] = String(testersConfig.snapshotHourUtc);
+    return fields.join(" ");
+  });
+  // Only declare a cron block when a spec actually carries one. An empty `crons` array is a declaration
+  // wrangler honors, and a worker advertising a schedule it does not have is a deployment nobody can
+  // reason about.
+  resolved.triggers = crons.length > 0 ? { crons } : undefined;
+
+  return resolved;
+}

package/src/roster/read.ts

@@ -0,0 +1,227 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { type Logger, noopLogger } from "@pithy-sh/core/src/logger/logger";
+import { resolveActivity, type TesterActivity } from "../activity/resolve";
+import { dayKey, daysSince } from "../clock/days";
+import { type CohortClock, readClock } from "../clock/replay";
+import type { TestersConfig } from "../config/config";
+import { TestersCohort } from "../data/cohort";
+import { TestersEvent } from "../data/event";
+import { TestersMember } from "../data/member";
+import { TestersCohortSnapshot } from "../data/snapshot";
+import {
+  TESTERS_COHORTS_TABLE,
+  TESTERS_EVENTS_TABLE,
+  TESTERS_MEMBERS_TABLE,
+  TESTERS_SNAPSHOTS_TABLE,
+  type TestersDatabase,
+} from "../data/tables";
+import { TestersCohortNotFoundError } from "../error/errors";
+import type { MemberReading } from "../projection/build";
+import { lastSignOfLife } from "../projection/build";
+
+/**
+ * Reading a cohort: the roster, the replayed clock, and whatever activity we can observe.
+ *
+ * One module for the read side so the control-plane route, the tester's own status route, the CLI, and
+ * the daily Workflow all see the same numbers. A second implementation anywhere would eventually
+ * disagree with this one, and the disagreement would show up as a dashboard and a terminal reporting
+ * different day counts for the same cohort — which would destroy the credibility of both.
+ */
+
+/** Milliseconds in one day. */
+const MS_PER_DAY = 86_400_000;
+
+/** Everything read for one cohort. */
+export interface CohortReading {
+  readonly cohort: TestersCohort;
+  readonly clock: CohortClock;
+  readonly readings: readonly MemberReading[];
+  /**
+   * The event log the clock was replayed from.
+   *
+   * Carried rather than discarded so a caller can replay the same events as of a different moment —
+   * the daily pass re-reads the finished previous day this way — without a second query for rows this
+   * read has already loaded.
+   */
+  readonly events: readonly TestersEvent[];
+}
+
+/** Load one cohort, or raise the capability's own 404. */
+export async function requireCohort(db: TestersDatabase, cohortId: string): Promise<TestersCohort> {
+  const row = await db.selectFrom(TESTERS_COHORTS_TABLE).selectAll().where("id", "=", cohortId).executeTakeFirst();
+  if (!row) throw new TestersCohortNotFoundError({ detail: `no cohort ${cohortId}` });
+  return TestersCohort.parse(row);
+}
+
+/** Load every cohort, newest first. */
+export async function listCohorts(db: TestersDatabase): Promise<TestersCohort[]> {
+  const rows = await db.selectFrom(TESTERS_COHORTS_TABLE).selectAll().orderBy("createdAt", "desc").execute();
+  return rows.map((row) => TestersCohort.parse(row));
+}
+
+/** Load a cohort's whole roster. */
+export async function listMembers(db: TestersDatabase, cohortId: string): Promise<TestersMember[]> {
+  const rows = await db
+    .selectFrom(TESTERS_MEMBERS_TABLE)
+    .selectAll()
+    .where("cohortId", "=", cohortId)
+    .orderBy("invitedAt", "asc")
+    .execute();
+  return rows.map((row) => TestersMember.parse(row));
+}
+
+/** Load a cohort's whole event history, oldest first — the order the clock replays in. */
+export async function listEvents(db: TestersDatabase, cohortId: string): Promise<TestersEvent[]> {
+  const rows = await db
+    .selectFrom(TESTERS_EVENTS_TABLE)
+    .selectAll()
+    .where("cohortId", "=", cohortId)
+    .orderBy("occurredAt", "asc")
+    .execute();
+  return rows.map((row) => TestersEvent.parse(row));
+}
+
+/** Load the trailing daily snapshots for a cohort, oldest first. */
+export async function listSnapshots(
+  db: TestersDatabase,
+  cohortId: string,
+  limit: number,
+): Promise<TestersCohortSnapshot[]> {
+  const rows = await db
+    .selectFrom(TESTERS_SNAPSHOTS_TABLE)
+    .selectAll()
+    .where("cohortId", "=", cohortId)
+    .orderBy("snapshotOn", "desc")
+    .limit(limit)
+    .execute();
+  return rows.map((row) => TestersCohortSnapshot.parse(row)).reverse();
+}
+
+/** One snapshot by day, for the trend deltas. */
+export async function snapshotOn(
+  db: TestersDatabase,
+  cohortId: string,
+  day: string,
+): Promise<TestersCohortSnapshot | undefined> {
+  const row = await db
+    .selectFrom(TESTERS_SNAPSHOTS_TABLE)
+    .selectAll()
+    .where("cohortId", "=", cohortId)
+    .where("snapshotOn", "=", day)
+    .executeTakeFirst();
+  return row ? TestersCohortSnapshot.parse(row) : undefined;
+}
+
+/** How many snapshots a cohort has. Drives whether a trend can be stated at all. */
+export async function countSnapshots(db: TestersDatabase, cohortId: string): Promise<number> {
+  const row = await db
+    .selectFrom(TESTERS_SNAPSHOTS_TABLE)
+    .select((eb) => eb.fn.countAll<number>().as("count"))
+    .where("cohortId", "=", cohortId)
+    .executeTakeFirst();
+  return Number(row?.count ?? 0);
+}
+
+/**
+ * Read one cohort in full: the roster, the replayed clock, and observed activity for every member.
+ *
+ * The activity lookup is batched across the whole roster rather than run per tester, because this runs
+ * inside a request as well as inside a Workflow, and a hundred-member cohort would otherwise be three
+ * hundred round trips before the first byte of a response.
+ *
+ * `log` is the caller's logger, passed straight through to {@link resolveActivity}. An unreadable
+ * activity read degrades the whole roster to "never signed in", which is indistinguishable from a
+ * genuinely inactive cohort — so the caller's logger is the only thing that says why. Defaults to the
+ * no-op so a caller with nothing to log through still reads.
+ */
+export async function readCohort(
+  db: TestersDatabase,
+  d1: D1Database,
+  cohort: TestersCohort,
+  config: TestersConfig,
+  now: Date,
+  log: Logger = noopLogger,
+): Promise<CohortReading> {
+  const members = await listMembers(db, cohort.id);
+  const events = await listEvents(db, cohort.id);
+
+  const clock = readClock(
+    {
+      createdAt: cohort.createdAt,
+      targetSize: cohort.targetSize,
+      windowDays: cohort.windowDays,
+      resetPolicy: cohort.resetPolicy,
+    },
+    events,
+    now,
+  );
+
+  const unreachable = new Set(members.filter((member) => member.unreachable).map((member) => member.email));
+  const activity = await resolveActivity(
+    d1,
+    members.map((member) => member.email),
+    {
+      since: new Date(now.getTime() - cohort.windowDays * MS_PER_DAY),
+      activeSince: new Date(now.getTime() - config.activeWithinDays * MS_PER_DAY),
+      unreachable,
+    },
+    log,
+  );
+
+  const readings: MemberReading[] = members.map((member) => ({
+    member,
+    activity:
+      activity.get(member.email) ??
+      ({
+        email: member.email,
+        userId: null,
+        observability: member.unreachable ? "unreachable" : "unobservable",
+        state: member.unreachable ? "unreachable" : "never_linked",
+        lastAuthenticatedAt: null,
+        sessionsInWindow: 0,
+        devices: [],
+      } satisfies TesterActivity),
+  }));
+
+  return { cohort, clock, readings, events };
+}
+
+/**
+ * How many observed testers first crossed into darkness in the last week.
+ *
+ * Feeds the trend sentence rather than the direction: "two testers went dark this week" is what a
+ * developer can act on, where "the forecast fell 0.07" is what a chart shows.
+ */
+export function newlyDark(readings: readonly MemberReading[], now: Date, threshold = 3): number {
+  return readings.filter((reading) => {
+    if (reading.activity.observability !== "observed" || !reading.activity.lastAuthenticatedAt) return false;
+    // The same opt-in floor the health score and the darkness histogram apply. This was the one
+    // darkness consumer left measuring from the raw last-authentication, so the trend sentence
+    // ("two testers went dark") could contradict the histogram on the very same snapshot row.
+    const dark = daysSince(lastSignOfLife(reading) ?? reading.activity.lastAuthenticatedAt, now);
+    return dark >= threshold && dark <= 7;
+  }).length;
+}
+
+/** The day key for `now`, so callers and the builder agree on which day they are writing. */
+export function todayKey(now: Date): string {
+  return dayKey(now);
+}
+
+/**
+ * Resolve a cohort by id or by name.
+ *
+ * The CLI takes whichever the developer has to hand, and a name is what they actually remember. Ids
+ * are tried first: a cohort deliberately named after another's id is a contrived case, and preferring
+ * the id keeps the lookup unambiguous for a management client that only ever has one.
+ */
+export async function resolveCohortRef(db: TestersDatabase, ref: string): Promise<TestersCohort> {
+  const byId = await db.selectFrom(TESTERS_COHORTS_TABLE).selectAll().where("id", "=", ref).executeTakeFirst();
+  if (byId) return TestersCohort.parse(byId);
+  const byName = await db.selectFrom(TESTERS_COHORTS_TABLE).selectAll().where("name", "=", ref).executeTakeFirst();
+  if (byName) return TestersCohort.parse(byName);
+  throw new TestersCohortNotFoundError({ detail: `no cohort with id or name ${ref}` });
+}