@pithy-sh/testers 0.1.0

package/src/capability.ts

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { DatabaseSpecMap } from "@pithy-sh/core/src/data/databases";
+import { workflowBindings } from "@pithy-sh/core/src/workflow/bindings";
+import type { EmailCapability } from "@pithy-sh/email/src/capability";
+import { isEmailCapability } from "@pithy-sh/email/src/capability";
+import type { Migration } from "kysely/migration";
+import { TestersConfig, type TestersConfigInput } from "./config/config";
+import { testersTables } from "./data/tables";
+import { registerTestersRoutes } from "./http/routes";
+import { testersAdminRoutes } from "./http/scopes";
+import { testers_0001_cohorts } from "./migrations/0001_cohorts";
+import type { EnqueueNudge } from "./nudge/send";
+import { testersExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+import { testersWorkflows } from "./workflows/specs";
+
+/**
+ * The testers capability: the roster, the invitations, and the fourteen-day clock.
+ *
+ * Composes into a Worker like any other capability. Its one hard dependency is `email` — an invitation
+ * that cannot be sent is not a testing program. `@pithy-sh/auth` is an **optional peer**: with it, testers who sign in
+ * become observable and the early-warning signal works; without it every tester resolves as
+ * unobservable, the forecast widens its band to say so, and everything else still runs.
+ */
+
+/**
+ * Where testers' migrations sort in the app database. Unique per database; the registry composes keys
+ * like `1200_testers_0001_cohorts`. Sits after the control-plane seam (1100), and was `NEXT_FREE_ORDER`
+ * when it was taken — see `packages/cli/src/migrations/orders.test.ts`, the only place an order is
+ * allocated.
+ */
+export const TESTERS_MIGRATION_ORDER = 1300;
+
+/** The database name every capability sharing the app D1 coordinates on. `DB` is the binding. */
+const TESTERS_DATABASE_NAME = "app" as const;
+
+/** The options `testers()` takes: the config's input side. */
+export type TestersOptions = TestersConfigInput;
+
+/** The testers capability, with its resolved config attached for tooling to read. */
+export interface TestersCapability
+  extends Capability<DatabaseSpecMap, Record<never, never>, "testers", typeof testersWorkflows> {
+  /** The resolved configuration. */
+  testersConfig: TestersConfig;
+}
+
+/** Whether a composed capability is the testers capability — carries its resolved config. */
+export function isTestersCapability(capability: Capability): capability is TestersCapability {
+  return capability.name === "testers" && "testersConfig" in capability;
+}
+
+/** Compose the testers capability. */
+export function testers(options: TestersOptions = {}): TestersCapability {
+  // Parsed at assembly rather than lazily: a target larger than the roster cap, or an opt-in link that
+  // expires before the window it belongs to closes, fails on deploy instead of on the day a tester
+  // clicks a link that no longer works.
+  const resolved = TestersConfig.parse(options);
+
+  const migrations: Record<string, Migration> = { "0001_cohorts": testers_0001_cohorts };
+
+  /**
+   * The email seam, filled by `compose`.
+   *
+   * Held in a mutable slot rather than passed in because `compose` runs after the factory: the routes
+   * are registered at assembly and need a way to reach an enqueue that does not exist yet.
+   */
+  const wiring: { enqueue: EmailCapability["enqueue"] | undefined } = { enqueue: undefined };
+
+  const requiredBindings: BindingSpecInput[] = [
+    // The app database — all four pithy_testers_* tables live here, alongside the pithy_auth_* tables
+    // the activity reader joins against.
+    { type: "d1", name: "DB" },
+    // The daily pass's Workflow binding, derived from the spec rather than written again, so a binding
+    // rename cannot leave the two disagreeing. Optional because the binding exists only once
+    // `pithy testers provision` has deployed the host, and an unprovisioned project must still be able
+    // to invite testers, accept confirmations, and read its cohorts.
+    ...workflowBindings(testersWorkflows),
+  ];
+
+  const capability = defineCapability({
+    name: "testers",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    // Email is the one hard dependency: a capability whose whole job is inviting people cannot ship
+    // with "and you supply the delivery". Secrets is deliberately NOT one — the confirmation token is a
+    // random value on the member row rather than a signature, so nothing here reads a secret, and
+    // `pithy testers invite` can build a working invitation against any environment.
+    dependsOn: ["email"],
+    config: TestersConfig,
+    workflows: testersWorkflows,
+    compose: ({ capabilities }) => {
+      const email = capabilities.find(isEmailCapability);
+      // `dependsOn` already fails assembly without it; this narrows the type and gives a message
+      // naming what testers actually wanted it for.
+      if (email) wiring.enqueue = email.enqueue;
+    },
+    requiredBindings,
+    databases: {
+      [TESTERS_DATABASE_NAME]: {
+        binding: "DB",
+        tables: testersTables(),
+        migrationOrder: TESTERS_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    // Built from the resolved `basePath`, never the default: an adopter who mounts this at `/beta` gets
+    // a manifest naming their paths, where a client assuming the default would 404.
+    adminRoutes: testersAdminRoutes(resolved.basePath),
+    routes: registerTestersRoutes({
+      config: resolved,
+      enqueue: (env) => {
+        const enqueue = wiring.enqueue;
+        if (!enqueue) return undefined;
+        // The email capability owns the `DB` and `EMAIL_SENDER` bindings and the from-identity; testers
+        // passes only the request env and the high-level input, and never names an email binding itself.
+        return ((input) => enqueue(env as never, input)) as EnqueueNudge;
+      },
+    }),
+    seeds: [testersExampleSeed],
+  });
+
+  return Object.assign(capability, { testersConfig: resolved });
+}

package/src/clock/days.ts

@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * UTC day keys — the `YYYY-MM-DD` strings the clock and the snapshot series are indexed by.
+ *
+ * **Why a string day rather than a timestamp.** Google's continuous-days counter runs on a day
+ * boundary that is neither documented nor readable, so Pithy picks one, uses it everywhere, and says
+ * which one it picked. UTC is the choice. Storing the day as text makes that choice total: the unique
+ * index on `(cohortId, snapshotOn)` is exact, day arithmetic never picks up an hour of drift from a
+ * server's locale, and two snapshots can never disagree about which day they describe because there is
+ * no timezone left in the value to disagree about.
+ *
+ * The consequence a developer must know, and the docs say so plainly: Pithy's day fourteen may not be
+ * Google's day fourteen. Which is one more reason not to start trusting the estimate on day thirteen.
+ */
+
+/** Milliseconds in one day. */
+const MS_PER_DAY = 86_400_000;
+
+/** A UTC day key: `YYYY-MM-DD`. */
+export type DayKey = string;
+
+/** The UTC day a moment falls in. */
+export function dayKey(at: Date): DayKey {
+  return at.toISOString().slice(0, 10);
+}
+
+/** Midnight UTC at the start of a day key — the instant the day begins. */
+export function startOfDay(day: DayKey): Date {
+  return new Date(`${day}T00:00:00.000Z`);
+}
+
+/** The last instant of a day key, inclusive. Everything at or before this happened on or before `day`. */
+export function endOfDay(day: DayKey): Date {
+  return new Date(startOfDay(day).getTime() + MS_PER_DAY - 1);
+}
+
+/** The day key `count` days after `day`. Negative counts go backwards. */
+export function addDays(day: DayKey, count: number): DayKey {
+  return dayKey(new Date(startOfDay(day).getTime() + count * MS_PER_DAY));
+}
+
+/**
+ * Whole days from `from` to `to`, signed. Exact rather than approximate, because both ends are
+ * midnight UTC by construction — no DST, no leap-second rounding, no off-by-one on the last day of a
+ * cohort.
+ */
+export function daysBetween(from: DayKey, to: DayKey): number {
+  return Math.round((startOfDay(to).getTime() - startOfDay(from).getTime()) / MS_PER_DAY);
+}
+
+/** Every day key from `from` to `to`, inclusive, ascending. Empty when `to` precedes `from`. */
+export function dayRange(from: DayKey, to: DayKey): DayKey[] {
+  const span = daysBetween(from, to);
+  if (span < 0) return [];
+  const days: DayKey[] = [];
+  for (let offset = 0; offset <= span; offset++) days.push(addDays(from, offset));
+  return days;
+}
+
+/**
+ * Whole days a moment is in the past, relative to `now`, floored at zero.
+ *
+ * Floored deliberately: a clock skew that puts a session's timestamp a few seconds in the future should
+ * read as "seen just now", not as negative days dark, which would score a tester as impossibly healthy.
+ */
+export function daysSince(at: Date, now: Date): number {
+  return Math.max(0, Math.floor((now.getTime() - at.getTime()) / MS_PER_DAY));
+}

package/src/clock/replay.ts

@@ -0,0 +1,190 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ResetPolicy } from "../config/config";
+import type { MemberState } from "../data/enums";
+import type { TestersEvent } from "../data/event";
+import { addDays, type DayKey, dayKey, dayRange, endOfDay } from "./days";
+
+/**
+ * The clock: roster state and the estimated continuous-day streak, replayed from the event log.
+ *
+ * **Nothing here reads a stored counter, and that is the design.** A counter can only be overwritten,
+ * which means a correction destroys both the old value and the evidence that it changed. Replaying
+ * makes a correction an insert: add the event that was missing, recompute, and every snapshot written
+ * before it survives as an accurate record of what Pithy believed on that day. A trend chart is
+ * claiming to show exactly that, so it has to be true.
+ *
+ * **This module computes Pithy's estimate. It is not Google's number and cannot be.** Google's opt-in
+ * streak is computed by Play Console and exposed by no API — not the count, not the streak, not a
+ * tester's opt-out. What is replayed here is our own record of who followed our own confirmation link,
+ * which is a well-informed estimate of Google's figure and diverges from it whenever a tester opts out
+ * without telling anyone. Every field this module produces is named `estimated*` for that reason.
+ */
+
+/** One member's opt-in history, reduced to the transitions the count depends on. */
+interface MemberTimeline {
+  memberId: string;
+  /** Every state-moving event, ascending. `nudged` and `reinvited` are dropped — they move nothing. */
+  transitions: { at: Date; kind: "invited" | "accepted" | "opted_in" | "lapsed" | "removed" }[];
+}
+
+/** The event kinds that move a member's state. The other two are outreach history. */
+const STATE_MOVING = new Set(["invited", "accepted", "opted_in", "lapsed", "removed"]);
+
+/**
+ * Group events into per-member timelines, ordered by when they *happened* rather than when they were
+ * written.
+ *
+ * The distinction is not pedantic. An opt-in confirmed on a phone with a stale clock, or a backfill
+ * that lands a week late, arrives with an `occurredAt` earlier than its `createdAt` — and replaying by
+ * insertion order would file it under the wrong day, which for a continuous-days counter is the
+ * difference between a completed window and a reset one.
+ */
+export function buildTimelines(events: readonly TestersEvent[]): Map<string, MemberTimeline> {
+  const timelines = new Map<string, MemberTimeline>();
+  for (const event of events) {
+    if (!STATE_MOVING.has(event.kind)) continue;
+    const timeline = timelines.get(event.memberId) ?? { memberId: event.memberId, transitions: [] };
+    timeline.transitions.push({
+      at: event.occurredAt,
+      kind: event.kind as MemberTimeline["transitions"][number]["kind"],
+    });
+    timelines.set(event.memberId, timeline);
+  }
+  for (const timeline of timelines.values()) {
+    timeline.transitions.sort((a, b) => a.at.getTime() - b.at.getTime());
+  }
+  return timelines;
+}
+
+/**
+ * A member's state as of the end of a given UTC day.
+ *
+ * The rule is "the last state-moving transition at or before this day wins", which is what makes
+ * re-opting-in work correctly: a tester who opted in, lapsed, and opted in again is counted from the
+ * second confirmation, and the days between do not count. Google's rule is the same — it explicitly
+ * does not credit fourteen non-consecutive days — so this is one of the few places the two models are
+ * known to agree.
+ */
+export function stateOn(timeline: MemberTimeline, day: DayKey): MemberState | undefined {
+  const cutoff = endOfDay(day).getTime();
+  let state: MemberState | undefined;
+  for (const transition of timeline.transitions) {
+    if (transition.at.getTime() > cutoff) break;
+    state = transition.kind;
+  }
+  return state;
+}
+
+/** How many members were opted in at the end of a given UTC day — Pithy's estimate of Google's count. */
+export function optedInOn(timelines: Map<string, MemberTimeline>, day: DayKey): number {
+  let count = 0;
+  for (const timeline of timelines.values()) {
+    if (stateOn(timeline, day) === "opted_in") count++;
+  }
+  return count;
+}
+
+/** What the clock reads for one cohort, as of one day. Every figure is an estimate. */
+export interface CohortClock {
+  /** The day this reading describes. */
+  readonly on: DayKey;
+  /** Pithy's estimate of the opted-in count on this day. */
+  readonly estimatedOptedInCount: number;
+  /** Whether the estimate reached the target on this day. */
+  readonly meetsTarget: boolean;
+  /** Estimated count minus target. Zero means one lapse from a reset; it can go negative. */
+  readonly headroom: number;
+  /** The estimated unbroken run of at-target days ending on this day. */
+  readonly estimatedHeldDays: number;
+  /** The day the current run began, or null while below target. */
+  readonly estimatedWindowStartOn: DayKey | null;
+  /** Window days still to hold, floored at zero. */
+  readonly estimatedDaysRemaining: number;
+  /** How many times the run has broken since the cohort started. */
+  readonly resetCount: number;
+  /** Whether the run broke on this day — the annotation a cohort chart most needs. */
+  readonly resetToday: boolean;
+  /** The full daily series the reading was computed from, oldest first. Feeds the chart and the tests. */
+  readonly series: readonly { day: DayKey; optedIn: number; meetsTarget: boolean }[];
+}
+
+/** What `readClock` needs to know about the cohort it is reading. */
+export interface ClockInput {
+  /** The cohort's creation moment — the first day of the series. */
+  readonly createdAt: Date;
+  /** The target in force. Read from the cohort row, not from config: the row's copy is frozen. */
+  readonly targetSize: number;
+  /** The window in force, in days. */
+  readonly windowDays: number;
+  /** What a dip below target does to the run. Pithy's assumption, not Google's documented behavior. */
+  readonly resetPolicy: ResetPolicy;
+}
+
+/**
+ * Read the clock for a cohort as of `now`.
+ *
+ * **On `resetPolicy`.** We do not know whether Play pauses or restarts the counter when a cohort dips
+ * to eleven. `reset` is the default and it is the pessimistic reading: it says you have further to go
+ * than `pause` would. That asymmetry is deliberate. A developer told they are on day fourteen when
+ * they are really on day three applies for production access, gets rejected, and blames the tool; a
+ * developer told day three when they were really on day fourteen waits an extra week and shrugs. Only
+ * one of those is worth defending against.
+ */
+export function readClock(input: ClockInput, events: readonly TestersEvent[], now: Date): CohortClock {
+  const timelines = buildTimelines(events);
+  const today = dayKey(now);
+  const start = dayKey(input.createdAt);
+  // A cohort created later than `now` (a clock skew, a seeded fixture) would otherwise produce an empty
+  // range and a series with no `today` in it, so the range is clamped to at least the current day.
+  const days = dayRange(start > today ? today : start, today);
+
+  const series = days.map((day) => {
+    const optedIn = optedInOn(timelines, day);
+    return { day, optedIn, meetsTarget: optedIn >= input.targetSize };
+  });
+
+  let resetCount = 0;
+  for (let index = 1; index < series.length; index++) {
+    // A break is a fall from at-target to below it. The first day of a cohort cannot be a break, and a
+    // cohort that has never reached target has never broken — it has simply not started.
+    if (series[index - 1]?.meetsTarget === true && series[index]?.meetsTarget === false) resetCount++;
+  }
+
+  const last = series[series.length - 1];
+  const meetsTarget = last?.meetsTarget ?? false;
+  const optedIn = last?.optedIn ?? 0;
+
+  let heldDays = 0;
+  if (input.resetPolicy === "pause") {
+    // Pause: every at-target day ever banked counts, whatever happened between them.
+    heldDays = series.filter((entry) => entry.meetsTarget).length;
+  } else {
+    // Reset: only the unbroken tail counts. Walk backwards until the run breaks.
+    for (let index = series.length - 1; index >= 0; index--) {
+      if (series[index]?.meetsTarget !== true) break;
+      heldDays++;
+    }
+  }
+
+  // The run's start is only meaningful under `reset`, where the tail is contiguous. Under `pause` the
+  // banked days need not be adjacent, so there is no single day the run "began" — reporting one would
+  // be inventing a fact to fill a field.
+  const windowStartOn = input.resetPolicy === "reset" && heldDays > 0 ? addDays(today, -(heldDays - 1)) : null;
+
+  const previous = series[series.length - 2];
+
+  return {
+    on: today,
+    estimatedOptedInCount: optedIn,
+    meetsTarget,
+    headroom: optedIn - input.targetSize,
+    estimatedHeldDays: heldDays,
+    estimatedWindowStartOn: windowStartOn,
+    estimatedDaysRemaining: Math.max(0, input.windowDays - heldDays),
+    resetCount,
+    resetToday: previous?.meetsTarget === true && !meetsTarget,
+    series,
+  };
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare
+// config in `vitest.workers.config.ts`: the app `DB` database the `pithy_testers_*` tables live in,
+// alongside the `pithy_auth_*` tables the activity reader joins against.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+  }
+}