@pithy-sh/testers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/testers
+
+The roster, the invitations, and the fourteen-day clock — for the closed test Google Play makes every new personal developer account run before it will grant production access.
+
+Twelve testers, opted in for fourteen continuous days. Lose one on day nine and the clock effectively restarts. There is no screen anywhere that tells you where you stand, which is the entire problem.
+
+```sh
+pithy add testers
+```
+
+**Documentation: [pithy.sh/docs/capabilities/testers](https://pithy.sh/docs/capabilities/testers).** Overview, adding it, using it, and the reference: the estimate, provisioning, what the store APIs cannot tell you.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT.

package/docs/store-apis.md

@@ -0,0 +1,107 @@
+# What the store APIs actually expose
+
+_The reader's version of this page is [pithy.sh/docs/capabilities/testers/store-apis](https://pithy.sh/docs/capabilities/testers/store-apis). This copy ships in the package because `packages/testers/src/crypto/token.ts` sends an adopter to it by name._
+
+This document exists because the most valuable thing `@pithy-sh/testers` can tell you is what it cannot do.
+
+Read it before assuming any part of this capability talks to Google. It does not. Nothing here reads the Play Console, and nothing here can.
+
+Every claim below carries the URL it came from. Where a claim is inferred rather than stated by the vendor, it says so.
+
+---
+
+## Google Play: the twelve-testers requirement
+
+The rule, verbatim from the authoritative page: developers with personal accounts created after November 13, 2023 must "run a closed test for your app with a minimum of 12 testers who have been opted-in for at least the last 14 days continuously." ([App testing requirements for new personal developer accounts](https://support.google.com/googleplay/android-developer/answer/14151465))
+
+Three details do most of the damage in practice.
+
+**The days must be consecutive.** Google states it outright: "we won't count testers who opted in, tested for less than 14 days, and then opted out. Even if they opt back in so that they are opted in for a total of 14 days, these 14 days must be consecutive." ([same page](https://support.google.com/googleplay/android-developer/answer/14151465)) Lose one tester on day nine and the clock effectively restarts.
+
+**Internal testing does not count.** Only closed testing satisfies the requirement. ([same page](https://support.google.com/googleplay/android-developer/answer/14151465))
+
+**It applies to personal accounts.** Organization accounts are not subject to it. ([same page](https://support.google.com/googleplay/android-developer/answer/14151465))
+
+The requirement launched at twenty testers and was later reduced to twelve, with the same fourteen-day window. Google maintains a [community guide](https://support.google.com/googleplay/android-developer/community-guide/255621488/everything-about-the-12-testers-requirement) on it. Treat "it used to be 20, it is now 12" as well established and the exact change date as unconfirmed — the secondary sources reporting December 11, 2024 are not Google.
+
+### The hundred-tester figure is about a different track
+
+You will see "maximum 100 testers" repeated widely. It is real, and it is about **internal** testing: "up to 100 testers per app." ([Set up an open, closed, or internal test](https://support.google.com/googleplay/android-developer/answer/9845334))
+
+**Closed testing — the track the requirement actually runs on — has no such cap.** Its limits are 2,000 users per email list, 50 lists per track, and 200 lists per account. ([same page](https://support.google.com/googleplay/android-developer/answer/9845334)) Google states no maximum tester count on the requirement page at all.
+
+This capability defaults a cohort's roster cap to 100 anyway, and the config field says why: a hundred is roughly the number of people one developer can still chase by hand. That is a management judgment, not a store limit, and you can raise it to 2,000.
+
+---
+
+## What the Play Developer API exposes
+
+Very little, and none of the part you want.
+
+**Tester management is Google-Groups-only.** The `edits.testers` resource has exactly one field — `googleGroups[]`, "All testing Google Groups, as email addresses." Its methods are `get`, `patch`, and `update`. There is no `list`, no per-tester resource, and no create or delete of an individual tester. ([edits.testers](https://developers.google.com/android-publisher/api-ref/rest/v3/edits.testers))
+
+The limitation is documented on every method: "while it is possible in the Play Console UI to add testers via email lists, email lists are not supported by this resource." ([edits.testers.get](https://developers.google.com/android-publisher/api-ref/rest/v3/edits.testers/get))
+
+So for the ordinary closed-testing setup — a list of email addresses added in the Console — the API is blind. It cannot read your roster, and it cannot write it.
+
+**The opt-in count is not readable.** Not the streak, not the plain count. The full v3 resource inventory contains no testing-metrics resource at all ([REST index](https://developers.google.com/android-publisher/api-ref/rest)), and the Play Developer Reporting API covers app quality — crashes, ANRs, wake-locks — not tester counts ([Play Developer Reporting](https://developers.google.com/play/developer/reporting)). The figure lives on one Play Console screen, and developers report it as unreliable even there ([thread](https://support.google.com/googleplay/android-developer/thread/312314620)).
+
+**Opt-out is not detectable.** There is no tester-state resource, and there is no webhook: Play's only push channel carries subscription and voided-purchase events, not testing events. Google clearly tracks opt-out server-side — its own wording depends on it — but exposes it only to its own eligibility check. ([REST index](https://developers.google.com/android-publisher/api-ref/rest))
+
+**What the API does cover** is release management: `edits.tracks` handles releases, version codes, staged-rollout fractions, country targeting, and halt/resume. ([edits.tracks](https://developers.google.com/android-publisher/api-ref/rest/v3/edits.tracks)) That is genuinely useful and genuinely not this capability.
+
+---
+
+## Apple TestFlight, for contrast
+
+App Store Connect exposes almost exactly what Google withholds.
+
+`GET /v1/betaTesters` returns the roster with `firstName`, `lastName`, `email`, `inviteType`, and **`state`** — and testers can be added and removed individually. ([List beta testers](https://developer.apple.com/documentation/appstoreconnectapi/get-v1-betatesters))
+
+`BetaTesterState` is a first-class readable attribute: `NOT_INVITED`, `INVITED`, `ACCEPTED`, `INSTALLED`, and `REVOKED` — where `REVOKED` means "The beta tester chose to stop testing, or was removed from the app." ([BetaTesterState](https://developer.apple.com/documentation/appstoreconnectapi/betatesterstate)) That is a machine-readable opt-out signal, which is the single largest gap between the two stores.
+
+Per-tester sessions and crashes are still Console-only, and excluded even from Apple's own CSV export. ([View and manage tester information](https://www.developer.apple.com/help/app-store-connect/test-a-beta-version/view-and-manage-tester-information))
+
+**Apple has no minimum-tester or minimum-duration requirement.** Nothing analogous to Google's twelve-for-fourteen exists. What Apple does have is guideline 2.2, which prohibits distributing TestFlight builds "in exchange for compensation of any kind" — so the paid-tester-farm ecosystem that grew around Google's rule is an App Review violation on iOS. ([App Review Guidelines](https://developer.apple.com/app-store/review/guidelines/))
+
+Auth is an ES256 JWT signed with a `.p8` key, and App Store Connect "rejects tokens with a lifetime greater than 20 minutes" for the TestFlight resources. ([Generating tokens](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests))
+
+---
+
+## The sequencing this forces
+
+Because the API cannot add an address to an email list, that step is manual — the developer does it in Play Console. And the opt-in link does not work for a tester until it is done: they get `App not available`, which reads to them as a broken app rather than as a step you have not taken yet.
+
+So the tester's journey has to be two messages, not one:
+
+1. **"Will you help test?"** — Pithy's own link, recording consent and confirming the address is deliverable and correct *before* it goes on a Google-visible list.
+2. You add the confirmed addresses to Play Console.
+3. **"You're on the list — here's the link"** — carrying the store's own opt-in page.
+
+Pithy's second link records the click and then *renders* the store link with instructions rather than redirecting to it. A 302 would make the adopter's Worker a redirector, and it would leave nowhere to say the two things that prevent most failures: open it in a browser rather than the store app, and sign in with the address the email reached you at.
+
+## What this capability therefore does
+
+It owns its own model, and says so everywhere.
+
+Pithy records who you invited, who agreed to test, and who followed the link through to the store, and replays a fourteen-day clock from those events. That is a well-informed estimate of the figure Google computes. It is not that figure, and the two diverge — most obviously when a tester opts out without telling anyone, which Google sees and Pithy cannot.
+
+Every field derived from it is named `estimated`. Every response carries a required `disclaimer` naming Google as the authority and stating that no API exposes it. `reconciliation.supported` is `false` with the reason attached, because "we checked and cannot" and "we never considered it" are different facts.
+
+**What Pithy reads that nobody else does is activity.** Because `@pithy-sh/auth` owns sessions and the device registry, a tester's invited address resolves to their user, and from there to when they last opened the app. That is fact, not estimate, and it is the only early-warning signal that exists: a tester dark for eight days is the one most likely to have quietly gone, and knowing on day eight beats discovering on day fourteen.
+
+Activity is never treated as opt-in continuity. A tester who confirmed and never opens the app still counts toward Google's twelve, so silence makes someone look alarming in the health column and never removes them from the count.
+
+The caveat that has to be stated rather than discovered: **activity exists only for testers who authenticate.** Someone who installs and never signs in is invisible, and an app whose test flow requires no sign-in produces no activity data at all. Those testers report `never_linked` rather than `inactive`, their health is `null` rather than a low score, and the forecast's confidence band widens to say how much of the cohort is unobservable.
+
+---
+
+## What a follow-up could add, and what it could not
+
+Store-API integration is viable, but only if it is scoped honestly.
+
+**Apple is worth building.** Roster reconciliation against `GET /v1/betaTesters`, opt-out alerting on the `REVOKED` transition, and feedback ingestion through the App Store Connect webhooks are all backed by documented endpoints. That is a real capability with no asterisks.
+
+**Google is release automation, not tester automation.** Track promotion, staged rollout, and country targeting are first-class; tester management is not. A follow-up framed around "testers" on the Google side would guarantee that the most-requested feature — the twelve-of-fourteen meter — is the one thing that cannot be built.
+
+**What must never be built:** a progress meter that claims to read Google's number. It would have to be either hand-entered by the developer or scraped from the Console, and scraping is fragile, terms-adjacent, and needs a real user session, which the service-account model does not have. A meter that looked authoritative and was neither would be worse than no meter at all.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pithy-sh/testers",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/testers"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "docs",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "peerDependencies": {
+    "@pithy-sh/auth": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@pithy-sh/auth": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/email": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "comment-json": "^5.0.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,52 @@
+{
+  "name": "testers",
+  "package": "@pithy-sh/testers",
+  "requiredBindings": [
+    {
+      "type": "d1",
+      "name": "DB"
+    },
+    {
+      "type": "workflow",
+      "name": "TESTERS_DAILY",
+      "job": "daily",
+      "className": "TestersDailyWorkflow",
+      "optional": true
+    }
+  ],
+  "peerCapabilities": ["email"],
+  "optionalCapabilities": ["auth", "controlplane", "audit", "secrets"],
+  "migrationNamespace": "testers",
+  "whenToEnable": "Google Play makes every new personal developer account run a closed test with at least 12 testers opted in for 14 continuous days before it will grant production access, and there is no screen anywhere that tells you where you stand. Lose one tester on day nine and the clock effectively starts again. This runs that process: a cohort with a target and a window, a roster you invite by email from your own domain, a one-tap confirmation link that needs no account, and a fourteen-day clock replayed from your own event log so a correction is a recomputation rather than an overwrite. The clock is honest about what it is. Pithy's count is an estimate from your own invite records; Google's count is authoritative and no API exposes it — not the roster, not the number, not a tester quietly opting out — so every figure derived from it is named `estimated`, the response carries that sentence as a required field, and nothing here claims to read the console. What Pithy can read is activity, and that is the part nobody else has: resolve each tester to their user through `@pithy-sh/auth` and you learn who has actually opened the app, so a tester dark for eight days shows up on day eight rather than on day fourteen when the count finally moves. A daily Workflow advances state, chases whoever needs chasing under a mandatory per-tester cooldown, and writes one snapshot per cohort per day — which is what makes the trend chartable at all, because activity cannot be reconstructed after the fact the way an event log can. Every nudge ships default copy, so this works from the CLI with no dashboard; a control-plane caller may override the words as plain text and never as markup, because those words go out over your own DKIM signature.",
+  "scaffold": [
+    "Add a `testers({ baseUrl: 'https://<your-worker>' })` block to pithy.config.ts. `baseUrl` is required before you can send an invitation — an email cannot carry a relative link.",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_testers_cohorts, pithy_testers_members, pithy_testers_events, and pithy_testers_cohort_snapshots.",
+    "Paste the store's opt-in link when you create the cohort — `pithy testers create <name> --store-url https://play.google.com/apps/testing/<package>`. Copy it from Play Console; it is where a tester actually enrols, and Pithy will not guess the format.",
+    "Add `email(...)` to the same Worker if it is not there already. Invitations and nudges are enqueued through it, so they inherit its retries, suppression list, and bounce handling.",
+    "Run `pithy testers provision` to deploy the daily-pass Worker and bind TESTERS_DAILY. It creates nothing else — no bucket, no secret — because the confirmation token is a random value on the tester's own row rather than a signature.",
+    "Create a cohort: `pithy testers create <name>`. It inherits your configured target and window and then freezes its own copy, so a later config change cannot rewrite whether last Tuesday counted.",
+    "Invite testers: `pithy testers invite <cohort> --email <address>`. Carry more than twelve — twelve is the number that must still be standing at the end, not the number to start with.",
+    "Watch it: `pithy testers status <cohort>` reports the estimated clock, observed activity, the forecast, and the trend. `--json` for an agent.",
+    "Run the pass: `pithy testers run` sends what is due, advances state, and records the day's snapshot. The provisioned Worker does the same at 05:00 UTC; `run` is how you exercise it now.",
+    "Read `docs/store-apis.md` in this package before assuming any of this talks to Google. It does not, and that document explains exactly what the Play Developer API does and does not expose."
+  ],
+  "configOptions": [
+    {
+      "key": "basePath",
+      "default": "/testers",
+      "describe": "Where the testers routes mount, the public opt-in link included. Change it and the confirmation links in already-sent invitations break, so pick it before you invite anybody."
+    },
+    {
+      "key": "baseUrl",
+      "default": "https://example.com",
+      "constant": "publicOrigin",
+      "describe": "The absolute origin the opt-in link is built from. Required before an invitation can be sent, because an email cannot carry a relative URL. Set it to the origin your Worker actually answers on, per environment."
+    },
+    {
+      "key": "modelVersion",
+      "default": "1",
+      "describe": "The label stamped on every daily snapshot identifying which set of survival and health constants produced its forecast. Bump it whenever you change one: a trend line silently spanning two models is a lie, and the dashboard uses this to annotate where your change took effect."
+    }
+  ]
+}

package/src/activity/resolve.ts

@@ -0,0 +1,273 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { messageOf } from "@pithy-sh/core/src/error/pithyError";
+import { type Logger, noopLogger } from "@pithy-sh/core/src/logger/logger";
+import type { TesterPlatform } from "../config/config";
+import type { ActivityState, Observability } from "../data/enums";
+
+/**
+ * Reading what testers actually did — the only figures in this package that are fact rather than
+ * estimate.
+ *
+ * **Activity is not a proxy for opt-in continuity, and conflating them would be the worst mistake this
+ * capability could make.** A tester who confirmed and never opens the app still counts toward Google's
+ * twelve. What activity buys is the only early-warning signal available: a tester dark for eight days
+ * is the one most likely to have quietly opted out or uninstalled, and that is actionable on day eight
+ * rather than on day fourteen when the count finally moves. So this module scores worry, never
+ * membership.
+ *
+ * **`@pithy-sh/auth` is an optional peer, reached through a guarded dynamic import.** A static import
+ * would make auth a hard dependency of a capability that works without it: a project whose test flow
+ * has no sign-in gets no activity data and should still be able to run cohorts, send invitations, and
+ * track the clock. When auth is absent, every tester resolves `unobservable` and the forecast widens
+ * its band to say so — which is exactly the right answer, and a much better one than failing to boot.
+ *
+ * **Two date encodings live in auth's own tables, and mixing them silently returns nothing.** Better
+ * Auth's columns (`pithy_auth_sessions`) are ISO-8601 **text**; Pithy's own (`pithy_auth_devices`) are
+ * ms-epoch **integers**. A window query written with the wrong codec compares a number to a string,
+ * matches no rows, and reports a perfectly active cohort as entirely dark. `JsonDate` for the first,
+ * `SQLiteDate` for the second — the comments at each call site say which and why.
+ */
+
+/** One registered device, as the roster view reports it. */
+export interface TesterDevice {
+  readonly platform: TesterPlatform | "web";
+  readonly lastSeenAt: Date;
+  readonly appVersion: string | null;
+}
+
+/** What we can observe about one tester. Every field here is fact; none of it is inferred. */
+export interface TesterActivity {
+  /** The invited address this reading is for, lowercased. */
+  readonly email: string;
+  /** The matched user's id, or null when the address never matched a user. */
+  readonly userId: string | null;
+  /** Whether we can see this tester at all, and why not when we cannot. */
+  readonly observability: Observability;
+  /** What the activity says. `never_linked` is deliberately distinct from `inactive`. */
+  readonly state: ActivityState;
+  /** The most recent sign of life — session refresh or device sighting. Null when never linked. */
+  readonly lastAuthenticatedAt: Date | null;
+  /** Sessions *active* inside the requested window — refreshed within it, whenever they were created. */
+  readonly sessionsInWindow: number;
+  /** Registered devices, most recently seen first. */
+  readonly devices: readonly TesterDevice[];
+}
+
+/** What the reader needs to know to interpret what it finds. */
+export interface ActivityOptions {
+  /** The start of the window sessions are counted inside. */
+  readonly since: Date;
+  /** A tester who authenticated at or after this is `active`. */
+  readonly activeSince: Date;
+  /** Addresses known to have bounced or be suppressed — reported `unreachable` whatever else we find. */
+  readonly unreachable: ReadonlySet<string>;
+}
+
+/** The auth modules this reader needs, or null when `@pithy-sh/auth` is not installed. */
+type AuthModules = {
+  authDatabase: typeof import("@pithy-sh/auth/src/data/tables").authDatabase;
+  User: typeof import("@pithy-sh/auth/src/data/betterAuth").User;
+  Device: typeof import("@pithy-sh/auth/src/data/device").Device;
+} | null;
+
+/**
+ * Load `@pithy-sh/auth`, or `null` if it is not installed.
+ *
+ * A missing optional peer is not an error here — it is a project that has no sign-in, which is a
+ * legitimate way to run a closed test. Returning null lets every tester resolve `unobservable`, which
+ * is the honest reading, rather than raising in a daily Workflow nobody is watching.
+ */
+async function loadAuth(): Promise<AuthModules> {
+  try {
+    const [tables, betterAuth, device] = await Promise.all([
+      import("@pithy-sh/auth/src/data/tables"),
+      import("@pithy-sh/auth/src/data/betterAuth"),
+      import("@pithy-sh/auth/src/data/device"),
+    ]);
+    return { authDatabase: tables.authDatabase, User: betterAuth.User, Device: device.Device };
+  } catch {
+    return null;
+  }
+}
+
+/** A tester we cannot see, with the reason stated rather than implied. */
+function blind(email: string, observability: Observability): TesterActivity {
+  return {
+    email,
+    userId: null,
+    observability,
+    state: observability === "unreachable" ? "unreachable" : "never_linked",
+    lastAuthenticatedAt: null,
+    sessionsInWindow: 0,
+    devices: [],
+  };
+}
+
+/**
+ * Resolve activity for a set of invited addresses.
+ *
+ * Batched by address rather than looked up one tester at a time: a hundred-member roster would
+ * otherwise be three hundred round trips inside a Workflow step. `chunkByBoundParameters` keeps each
+ * `IN (…)` inside D1's statement limits.
+ *
+ * **`log` is the caller's logger, not one built here, because this reader has two callers of different
+ * shapes.** It runs inside the daily Workflow, and it runs inside `GET /testers/status` and
+ * `GET /testers/cohorts` — so a request reaches it, and a request logger already carries the
+ * correlation an operator needs. Building a fresh one here would emit the line that explains an empty
+ * roster with nothing tying it to the request that asked for it. Defaults to the no-op so a caller with
+ * no logger reads activity rather than null-checking.
+ */
+export async function resolveActivity(
+  d1: D1Database,
+  emails: readonly string[],
+  options: ActivityOptions,
+  log: Logger = noopLogger,
+): Promise<Map<string, TesterActivity>> {
+  const normalized = [...new Set(emails.map(normalizeAddress))];
+  const results = new Map<string, TesterActivity>();
+  for (const email of normalized) {
+    results.set(email, blind(email, options.unreachable.has(email) ? "unreachable" : "unobservable"));
+  }
+  if (normalized.length === 0) return results;
+
+  const auth = await loadAuth();
+  if (!auth) return results;
+
+  try {
+    await readActivityInto(results, auth, d1, normalized, options);
+  } catch (error) {
+    // The auth tables are not there — the package is installed but its migration has not run, or this
+    // project composes testers without composing auth. Either way it is the same fact as an uninstalled
+    // package, and it must degrade the same way: every tester resolves `unobservable`, the forecast
+    // widens its band to say so, and the daily pass still advances state and records the day. Throwing
+    // here would take down a cron at 05:00 over data that was never promised to exist.
+    //
+    // Logged rather than silent, because the other thing this catch swallows is a transient D1 failure,
+    // and that records a cohort as entirely dark for a day with no trace of why. An operator reading a
+    // sudden coverage cliff needs somewhere to look. `warn` rather than `error`: the reading degraded,
+    // the caller carried on, and a project that simply has no auth would otherwise page somebody.
+    log.warn("activity unreadable, treating the roster as unobservable", {
+      addresses: normalized.length,
+      reason: messageOf(error),
+    });
+  }
+  return results;
+}
+
+/** Fill in what the auth tables can tell us about these addresses. Throws if they are not there. */
+async function readActivityInto(
+  results: Map<string, TesterActivity>,
+  auth: NonNullable<AuthModules>,
+  d1: D1Database,
+  normalized: readonly string[],
+  options: ActivityOptions,
+): Promise<void> {
+  const db = auth.authDatabase(d1);
+
+  // Address → user. Auth's `email` column is unique and every Pithy sign-in is provider-verified, so
+  // this is an exact match with no ambiguity to resolve.
+  const users: { id: string; email: string }[] = [];
+  for (const chunk of chunkByBoundParameters(normalized, 0)) {
+    const rows = await db.selectFrom("pithyAuthUsers").select(["id", "email"]).where("email", "in", chunk).execute();
+    for (const row of rows) users.push({ id: String(row.id), email: normalizeAddress(String(row.email)) });
+  }
+  if (users.length === 0) return;
+
+  const userIds = users.map((user) => user.id);
+  const emailByUserId = new Map(users.map((user) => [user.id, user.email]));
+
+  // Sessions in the window. `createdAt` is ISO-8601 TEXT on this table — Better Auth's own encoding —
+  // so the bound must be `JsonDate`. `SQLiteDate` here would compare a number against a string, match
+  // nothing, and report every tester as dark.
+  const sessions = new Map<string, { count: number; lastSeen: Date | null }>();
+  for (const chunk of chunkByBoundParameters(userIds, 1)) {
+    const rows = await db
+      .selectFrom("pithyAuthSessions")
+      .select(["userId", "createdAt", "updatedAt"])
+      .where("userId", "in", chunk)
+      // Bounded on `updatedAt`, which is the column the reading below actually uses. Filtering on
+      // `createdAt` excluded the long-lived session — created before the window, refreshed inside it
+      // every day since — and reported its owner as dark. That is the most engaged tester there is.
+      .where("updatedAt", ">=", JsonDate.encode(options.since))
+      .execute();
+    for (const row of rows) {
+      const userId = String(row.userId);
+      const entry = sessions.get(userId) ?? { count: 0, lastSeen: null };
+      entry.count++;
+      // `updatedAt` slides forward when a session is refreshed, so it is a genuine "last seen the app"
+      // signal rather than "last signed in" — which token rotation would otherwise reset.
+      const seen = JsonDate.parse(row.updatedAt ?? row.createdAt);
+      if (!entry.lastSeen || seen > entry.lastSeen) entry.lastSeen = seen;
+      sessions.set(userId, entry);
+    }
+  }
+
+  // Devices. This is a Pithy-owned table, so `lastSeenAt` is a ms-epoch INTEGER and the codec is
+  // `SQLiteDate`. Devices cover the tester whose long-lived session is refreshed off-device.
+  const devices = new Map<string, TesterDevice[]>();
+  for (const chunk of chunkByBoundParameters(userIds, 0)) {
+    const rows = await db
+      .selectFrom("pithyAuthDevices")
+      .selectAll()
+      .where("userId", "in", chunk)
+      .orderBy("lastSeenAt", "desc")
+      .execute();
+    for (const row of rows) {
+      const parsed = auth.Device.parse(row);
+      const list = devices.get(parsed.userId) ?? [];
+      list.push({ platform: parsed.platform, lastSeenAt: parsed.lastSeenAt, appVersion: parsed.appVersion });
+      devices.set(parsed.userId, list);
+    }
+  }
+
+  for (const [userId, email] of emailByUserId) {
+    if (options.unreachable.has(email)) continue; // Unreachable overrides whatever we can see.
+
+    const session = sessions.get(userId);
+    const deviceList = devices.get(userId) ?? [];
+    const lastDevice = deviceList[0]?.lastSeenAt ?? null;
+    const lastSession = session?.lastSeen ?? null;
+    const lastAuthenticatedAt =
+      lastSession && lastDevice ? (lastSession > lastDevice ? lastSession : lastDevice) : (lastSession ?? lastDevice);
+
+    // A user row with no session and no device is a match we cannot learn anything from. Calling it
+    // `observed` would let a tester with zero signal score as merely quiet, when the truth is that we
+    // have never seen them use the app at all.
+    if (!lastAuthenticatedAt) {
+      results.set(email, blind(email, "unobservable"));
+      continue;
+    }
+
+    const state: ActivityState = lastAuthenticatedAt >= options.activeSince ? "active" : "inactive";
+    results.set(email, {
+      email,
+      userId,
+      observability: "observed",
+      state,
+      lastAuthenticatedAt,
+      sessionsInWindow: session?.count ?? 0,
+      devices: deviceList,
+    });
+  }
+}
+
+/** Whether any of a tester's devices runs the cohort's target platform. */
+export function hasPlatformDevice(activity: TesterActivity, platform: TesterPlatform | null): boolean {
+  if (platform === null) return true;
+  return activity.devices.some((device) => device.platform === platform);
+}
+
+/** The most recent device sighting, for a tester whose sessions have all rotated away. */
+export function lastDeviceSeen(activity: TesterActivity): Date | null {
+  let latest: Date | null = null;
+  for (const device of activity.devices) {
+    if (!latest || device.lastSeenAt > latest) latest = device.lastSeenAt;
+  }
+  return latest;
+}

package/src/audit/actions.ts

@@ -0,0 +1,56 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The audit actions this capability emits, through the core `emit()` seam.
+ *
+ * Every roster change is audited, because a roster is a list of real people's email addresses that a
+ * management credential can add to, remove from, and mail. "Who took Ada off the cohort on the twelfth,
+ * and what did the dashboard send to the other eleven that afternoon" is a question with an answer, and
+ * these are what make it one.
+ *
+ * Emitted with `c.var.emit`, never by importing `@pithy-sh/audit` — the seam is always present
+ * (`noopEmit` when no audit capability is composed), so there is no null check and no hard dependency.
+ * Identifiers and outcomes only in metadata: never a token, never the body of a nudge.
+ */
+export const TestersAuditActions = {
+  /** A cohort was created. The start of a roster's life, and the frozen copy of its rules. */
+  /** An address was added to a roster. A real person's email address, added by whoever held the credential. */
+  memberInvited: "testers/member_invited",
+  /** Another invitation went to someone already on the roster. */
+  memberReinvited: "testers/member_reinvited",
+  /**
+   * A tester answered the invitation and agreed to test.
+   *
+   * Audited separately from the opt-in because it is the developer's cue to put a real person's address
+   * on a store tester list — a list Google can see. When that address got there, and on whose say-so, is
+   * a question worth being able to answer.
+   */
+  memberAccepted: "testers/member_accepted",
+  /**
+   * A tester followed the confirmation link.
+   *
+   * Audited because it is the single event the entire opt-in count rests on. If the count is ever
+   * disputed, this is the trail that says when each confirmation arrived and from where.
+   */
+  memberOptedIn: "testers/member_opted_in",
+  /** A tester followed the opt-out link. Their own act, recorded as theirs. */
+  memberLapsed: "testers/member_lapsed",
+  /** A tester was taken off a roster by the developer. */
+  memberRemoved: "testers/member_removed",
+  /**
+   * A nudge was enqueued.
+   *
+   * Audited with the copy's provenance rather than its text: knowing that a message went out over the
+   * adopter's own sending domain, to whom, and whether the words were Pithy's or a caller's, is what
+   * makes a leaked dashboard credential investigable after the fact.
+   */
+  nudgeSent: "testers/nudge_sent",
+  /** A nudge was refused because every selected tester was inside the cooldown. */
+  nudgeThrottled: "testers/nudge_throttled",
+  /** A caller supplied nudge copy on a deployment that pins the defaults. */
+  copyRejected: "testers/copy_rejected",
+} as const;
+
+/** One of the testers capability's audit actions. */
+export type TestersAuditAction = (typeof TestersAuditActions)[keyof typeof TestersAuditActions];