@pithy-sh/testers 0.1.0

package/src/http/schemas.ts

@@ -0,0 +1,210 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { OPT_IN_TOKEN_PATTERN } from "../crypto/token";
+import { NudgeKind } from "../data/enums";
+
+/**
+ * Every request contract this capability accepts. There is nowhere else input may be declared, and no
+ * handler parses anything itself — a handler receives typed values, so the route signature carries the
+ * whole contract.
+ *
+ * **What is deliberately absent is as much of the design as what is here.** No request names a sender,
+ * a signing key, or an environment: those come from the deployment. No request supplies a tester's
+ * opt-in date: that comes from the link they followed. And no request accepts HTML anywhere, for
+ * the reason `nudge/copy.ts` sets out at length — words go out over the adopter's own DKIM signature,
+ * so bounding the input to text is what bounds the blast radius of a leaked dashboard credential.
+ */
+
+/** The longest a cohort or tester name may be in a request. Matches the config bound. */
+const MAX_NAME_LENGTH = 120;
+
+/** The longest an overridden subject may be. Longer is truncated by every mail client anyway. */
+const MAX_SUBJECT_LENGTH = 200;
+
+/**
+ * The longest an overridden body may be.
+ *
+ * Generous for a nudge and small enough that a flood of them cannot be a rendering denial of service.
+ * The config bound may be tighter; this is the ceiling the route will parse at all.
+ */
+const MAX_BODY_LENGTH = 20_000;
+
+/**
+ * The path parameter carrying an opt-in or opt-out token.
+ *
+ * This bounds the *shape* of the segment; it does not authenticate anything and must not be mistaken
+ * for doing so. A well-formed token that belongs to nobody still fails, with the capability's own
+ * `testers/invalid_token` — the same code a real lookup miss raises, and deliberately so: a malformed
+ * segment is answered by the validator with `validation/invalid_input`, so the two failures a caller
+ * can tell apart are "that is not a token" and "that token opens nothing", never "that token belongs
+ * to somebody else".
+ */
+export const OptInTokenParam = z
+  .object({
+    token: z
+      .string()
+      // The generator's own pattern, imported rather than restated. These two drifted apart once
+      // already — the schema still described the old signed `payload.signature` form after the token
+      // became a single 43-character value — and every tester link 400'd before reaching a handler.
+      .regex(OPT_IN_TOKEN_PATTERN)
+      .describe(
+        "The confirmation token from the path. Shape only, and deliberately not authenticity: a well-formed token matching no member still fails, with the same words.",
+      ),
+  })
+  .describe("The path parameter carrying a testers opt-in or opt-out token.");
+export type OptInTokenParam = z.infer<typeof OptInTokenParam>;
+
+/** Creating a cohort. Every field but the name inherits from config when omitted. */
+export const CreateCohortRequest = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(MAX_NAME_LENGTH)
+      .describe("A human label for the cohort, unique within the project. Shown in the CLI and the dashboard."),
+    targetSize: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "How many testers must be opted in simultaneously. Defaults to the configured value — twelve, for Google Play.",
+      ),
+    windowDays: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "How many continuous days the target must hold. Defaults to the configured value — fourteen, for Google Play.",
+      ),
+    maxRosterSize: z.number().int().positive().optional().describe("The roster cap. Defaults to the configured value."),
+    targetPlatform: z
+      .enum(["android", "ios"])
+      .optional()
+      .describe("Which store's program this cohort serves. Defaults to the configured value."),
+  })
+  .describe(
+    "Create a testing cohort. Omitted fields inherit the project's configured defaults and are then frozen on the row.",
+  );
+export type CreateCohortRequest = z.infer<typeof CreateCohortRequest>;
+
+/** Inviting one address onto a cohort. */
+export const InviteRequest = z
+  .object({
+    cohortId: z.string().min(1).describe("The cohort to invite them onto."),
+    email: z
+      .email()
+      .max(320)
+      .describe("The tester's address. Lowercased on write, and the join key to the user record if they ever sign in."),
+    name: z.string().max(MAX_NAME_LENGTH).nullish().describe("A display name for the roster. Optional."),
+    sendInvitation: z
+      .boolean()
+      .default(true)
+      .describe(
+        "Whether to email the confirmation link now. False adds them to the roster silently — for importing a list of people already contacted elsewhere, so their history starts in the right place.",
+      ),
+  })
+  .describe("Invite one address onto a cohort.");
+export type InviteRequest = z.output<typeof InviteRequest>;
+
+/** Sending another invitation to someone already on the roster. */
+export const ResendRequest = z
+  .object({
+    memberId: z.string().min(1).describe("The roster member to send another invitation to."),
+  })
+  .describe("Send another invitation, preserving the tester's existing history and their original invited date.");
+export type ResendRequest = z.infer<typeof ResendRequest>;
+
+/** Taking a tester off a cohort. */
+export const RemoveRequest = z
+  .object({
+    memberId: z.string().min(1).describe("The roster member to remove."),
+    reason: z
+      .string()
+      .max(200)
+      .optional()
+      .describe("A short note recorded on the event, for the developer's own records. Never shown to the tester."),
+  })
+  .describe("Take a tester off a cohort's roster. Recorded as the developer's act, not the tester's.");
+export type RemoveRequest = z.infer<typeof RemoveRequest>;
+
+/**
+ * Triggering a nudge.
+ *
+ * **`subject` and `body` are the only overridable fields, and both are plain text.** There is no HTML
+ * field, no template id, and no layout option, because this Worker owns the envelope and signs it with
+ * the adopter's domain. `body` is split into paragraphs and each renders HTML-escaped, so markup
+ * arrives as visible text rather than as markup — structurally, not by filtering.
+ */
+export const NudgeRequest = z
+  .object({
+    cohortId: z.string().min(1).describe("The cohort whose testers to nudge."),
+    kind: NudgeKind.describe(
+      "Which nudge to send. Decides the default copy and, for `confirm`, whether a link is attached.",
+    ),
+    memberIds: z
+      .array(z.string().min(1))
+      .max(500)
+      .optional()
+      .describe(
+        "Specific testers to nudge. Omit to let the kind select them — `confirm` targets everyone who has not confirmed, `inactive` everyone who has gone quiet.",
+      ),
+    subject: z
+      .string()
+      .max(MAX_SUBJECT_LENGTH)
+      .optional()
+      .describe(
+        "An overridden subject line, as plain text. Control characters and newlines are stripped before it reaches the renderer, because a newline in a header is how a subject becomes an injected one.",
+      ),
+    body: z
+      .string()
+      .max(MAX_BODY_LENGTH)
+      .optional()
+      .describe(
+        "An overridden body, as PLAIN TEXT only. Blank lines separate paragraphs. Markup is not accepted and not stripped — it is escaped, so it reaches the recipient as visible characters. There is no field that accepts HTML, deliberately: supplied words go out over your own DKIM signature.",
+      ),
+    dryRun: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Report who would be nudged and enqueue nothing. The safe way to check a selection before mailing twelve people.",
+      ),
+  })
+  .describe(
+    "Trigger a nudge to selected testers. The per-tester cooldown is enforced server-side on this path and cannot be overridden by the caller.",
+  );
+export type NudgeRequest = z.output<typeof NudgeRequest>;
+
+/** Reading cohort state. Cheap by default; the expensive parts are opt-in. */
+export const CohortsQuery = z
+  .object({
+    cohortId: z.string().min(1).optional().describe("Restrict to one cohort. Omit for every cohort in this Worker."),
+    members: z
+      .stringbool()
+      .default(false)
+      .describe("Include the full roster with per-tester activity and health. Costs the roster join."),
+    trend: z
+      .stringbool()
+      .default(false)
+      .describe("Include the trailing daily snapshots the chart is drawn from. Costs `trendDays` rows per cohort."),
+    trendDays: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(180)
+      .default(30)
+      .describe("How many trailing daily snapshots to return when `trend` is set."),
+  })
+  .describe("Query contract for the control-plane cohort read. The summary is one row per cohort; extras are opt-in.");
+export type CohortsQuery = z.output<typeof CohortsQuery>;
+
+/** A tester reading their own position. */
+export const StatusQuery = z
+  .object({
+    cohortId: z.string().min(1).optional().describe("Restrict to one cohort. Omit for every cohort this tester is on."),
+  })
+  .describe("Query contract for a tester's own view of where they stand.");
+export type StatusQuery = z.output<typeof StatusQuery>;

package/src/http/scopes.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * Testers' control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+ * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
+ * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
+ * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
+ * one compiled `PithyHonoEnv`, which reached core's `capability.ts`, which named Worker globals that
+ * program has none of. **This module imports types and nothing else, and a gate holds it there**:
+ * `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
+ */
+
+/**
+ * The scopes this capability's admin routes require.
+ *
+ * One scope per operation, matched by exact string equality — there is no prefix rule and no wildcard.
+ * A single `testers:admin` flag would mean a dashboard credential issued to read a roster could also
+ * mail every person on it, and mailing is the operation with a blast radius outside the adopter's own
+ * systems.
+ */
+export const TESTERS_ROSTER_READ_SCOPE: ControlPlaneScope = "testers:roster:read";
+export const TESTERS_ROSTER_WRITE_SCOPE: ControlPlaneScope = "testers:roster:write";
+export const TESTERS_NUDGE_SEND_SCOPE: ControlPlaneScope = "testers:nudge:send";
+
+/** Every control-plane scope this capability defines. */
+export const TESTERS_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  TESTERS_ROSTER_READ_SCOPE,
+  TESTERS_ROSTER_WRITE_SCOPE,
+  TESTERS_NUDGE_SEND_SCOPE,
+];
+
+/**
+ * The admin routes this capability advertises on `GET /control-plane/manifest`.
+ *
+ * Built from the **resolved** `basePath`, never the default. An adopter who mounts this at `/beta` gets
+ * a manifest naming `/beta/testers/...`, where a client assuming the default would 404 — and the whole
+ * point of the manifest is that a management client composes its calls from the Worker rather than from
+ * a route table it shipped with.
+ */
+export function testersAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/cohorts`,
+      scope: TESTERS_ROSTER_READ_SCOPE,
+      summary: "Cohort state, roster, per-tester activity, the forecast, and the trend series.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/invite`,
+      scope: TESTERS_ROSTER_WRITE_SCOPE,
+      summary: "Invite an address onto a cohort and send its confirmation link.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/resend`,
+      scope: TESTERS_ROSTER_WRITE_SCOPE,
+      summary: "Send another invitation, preserving the tester's existing history.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/remove`,
+      scope: TESTERS_ROSTER_WRITE_SCOPE,
+      summary: "Take a tester off a cohort's roster.",
+    },
+    {
+      method: "POST",
+      path: `${basePath}/nudge`,
+      scope: TESTERS_NUDGE_SEND_SCOPE,
+      summary: "Nudge selected testers. Copy may be overridden as text; the cooldown is enforced here.",
+    },
+  ];
+}

package/src/http/view.ts

@@ -0,0 +1,304 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { hasPlatformDevice } from "../activity/resolve";
+import { dayKey, daysSince } from "../clock/days";
+import type { TestersConfig } from "../config/config";
+import type { TestersCohortSnapshot } from "../data/snapshot";
+import { scoreHealth, survivalFor } from "../health/score";
+import { cooldownUntil } from "../nudge/cooldown";
+import type { MemberReading } from "../projection/build";
+import { type ForecastMember, forecastCohort, type PipelineMember } from "../projection/forecast";
+import { cohortAgeDays, conversionLatency } from "../projection/inputs";
+import type { CohortReading } from "../roster/read";
+import { LIVE_STATES } from "../roster/write";
+import { type CohortView, DISCLAIMER, type MemberView, type SnapshotView, type TrendView } from "./responses";
+
+/**
+ * Turning a cohort reading into the shape a dashboard receives.
+ *
+ * The one rule this file exists to enforce is the separation the response schema declares: the
+ * estimated half and the observed half go into different objects, each carrying a literal `source`, and
+ * the disclaimer is attached unconditionally rather than by any code path that could be missed. There
+ * is no branch here that produces a cohort without it.
+ */
+
+/** An ISO string, or null. */
+function iso(date: Date | null | undefined): string | null {
+  return date ? date.toISOString() : null;
+}
+
+/** Build one tester's view, health included. */
+function memberView(
+  reading: MemberReading,
+  cohortReading: CohortReading,
+  config: TestersConfig,
+  now: Date,
+): MemberView {
+  const { member, activity } = reading;
+  const optedInAt = member.optedInAt;
+
+  // The dark clock floors at the opt-in date, so a tester who confirmed this morning reads as fresh
+  // rather than as however long ago they were first invited.
+  const lastSignOfLife = [activity.lastAuthenticatedAt, optedInAt]
+    .filter((date): date is Date => date !== null)
+    .reduce<Date | null>((latest, date) => (latest === null || date > latest ? date : latest), null);
+
+  const daysDark =
+    activity.observability === "observed" && lastSignOfLife !== null ? daysSince(lastSignOfLife, now) : null;
+
+  const health = scoreHealth(
+    {
+      observability: activity.observability,
+      daysDark,
+      sessionsInWindow: activity.sessionsInWindow,
+      deviceCount: activity.devices.length,
+      hasTargetPlatformDevice: hasPlatformDevice(activity, cohortReading.cohort.targetPlatform),
+      sessionSinceOptIn:
+        optedInAt !== null && activity.lastAuthenticatedAt !== null && activity.lastAuthenticatedAt >= optedInAt,
+      unansweredNudges: member.nudgeCount,
+      daysSinceOptIn: optedInAt === null ? null : daysSince(optedInAt, now),
+      targetPlatform: cohortReading.cohort.targetPlatform,
+    },
+    config.healthPenalties,
+    config.healthCredits,
+  );
+
+  return {
+    id: member.id,
+    email: member.email,
+    name: member.name,
+    state: member.state,
+    invitedAt: member.invitedAt.toISOString(),
+    acceptedAt: iso(member.acceptedAt),
+    estimatedOptedInAt: iso(member.optedInAt),
+    lapsedAt: iso(member.lapsedAt),
+    estimatedOptInDays: optedInAt === null ? 0 : daysSince(optedInAt, now),
+    activity: {
+      source: "observed",
+      observability: activity.observability,
+      state: activity.state,
+      lastAuthenticatedAt: iso(activity.lastAuthenticatedAt),
+      // Only an `inactive` tester has a "since". A never-linked one has no date to report, and
+      // inventing one would erase the distinction the whole activity model turns on.
+      inactiveSince: activity.state === "inactive" ? iso(activity.lastAuthenticatedAt) : null,
+      daysDark,
+      sessionsInWindow: activity.sessionsInWindow,
+      devices: activity.devices.map((device) => ({
+        platform: device.platform,
+        lastSeenAt: device.lastSeenAt.toISOString(),
+        appVersion: device.appVersion,
+      })),
+    },
+    health: health.health,
+    healthBasis: health.basis,
+    riskBand: health.riskBand,
+    dailySurvival: survivalFor(health.riskBand, activity.observability, config.survival),
+    factors: health.factors.map((factor) => ({ ...factor })),
+    lastNudgedAt: iso(member.lastNudgedAt),
+    nudgeCooldownUntil: iso(cooldownUntil(member, config.nudges.cooldownHours)),
+    unreachable: member.unreachable,
+  };
+}
+
+/** Project a stored snapshot into the chart's point shape. */
+export function snapshotView(snapshot: TestersCohortSnapshot): SnapshotView {
+  return {
+    snapshotOn: snapshot.snapshotOn,
+    dayIndex: snapshot.dayIndex,
+    backfilled: snapshot.backfilled,
+    modelVersion: snapshot.modelVersion,
+    rosterSize: snapshot.rosterSize,
+    invitedCount: snapshot.invitedCount,
+    acceptedCount: snapshot.acceptedCount,
+    estimatedOptedInCount: snapshot.estimatedOptedInCount,
+    lapsedCount: snapshot.lapsedCount,
+    targetSize: snapshot.targetSize,
+    meetsTarget: snapshot.meetsTarget,
+    headroom: snapshot.headroom,
+    estimatedHeldDays: snapshot.estimatedHeldDays,
+    estimatedDaysRemaining: snapshot.estimatedDaysRemaining,
+    resetToday: snapshot.resetToday,
+    resetCount: snapshot.resetCount,
+    activeCount: snapshot.activeCount,
+    darkThreeToSevenCount: snapshot.darkThreeToSevenCount,
+    darkEightToThirteenCount: snapshot.darkEightToThirteenCount,
+    darkFourteenPlusCount: snapshot.darkFourteenPlusCount,
+    neverLinkedCount: snapshot.neverLinkedCount,
+    observedCoverage: snapshot.observedCoverage,
+    medianHealth: snapshot.medianHealth,
+    minHealth: snapshot.minHealth,
+    successProbability: snapshot.successProbability,
+    successProbabilityLow: snapshot.successProbabilityLow,
+    successProbabilityHigh: snapshot.successProbabilityHigh,
+    expectedSurvivors: snapshot.expectedSurvivors,
+    invitesNeeded: snapshot.invitesNeeded,
+    trendDirection: snapshot.trendDirection,
+    trendReason: snapshot.trendReason,
+    fragile: snapshot.fragile,
+    nudgesSent: snapshot.nudgesSent,
+  };
+}
+
+/** What the view needs beyond the reading itself. */
+export interface ViewOptions {
+  readonly includeMembers: boolean;
+  /** Trailing snapshots, oldest first. Empty when the trend was not requested. */
+  readonly snapshots: readonly TestersCohortSnapshot[];
+  /** The most recent snapshot, whether or not the series was requested — it carries the precomputed trend. */
+  readonly latest: TestersCohortSnapshot | undefined;
+}
+
+/** Assemble the cohort view a dashboard receives. */
+export function toCohortView(
+  reading: CohortReading,
+  config: TestersConfig,
+  options: ViewOptions,
+  now: Date,
+): CohortView {
+  const { cohort, clock, readings } = reading;
+
+  const members = readings.map((entry) => memberView(entry, reading, config, now));
+  const byState = (state: string) => members.filter((member) => member.state === state).length;
+  const optedIn = members.filter((member) => member.state === "opted_in");
+  const observed = optedIn.filter((member) => member.activity.observability === "observed");
+
+  const today = dayKey(now);
+  const forecast = forecastCohort({
+    today,
+    targetSize: cohort.targetSize,
+    optedInCount: clock.estimatedOptedInCount,
+    daysRemaining: clock.estimatedDaysRemaining,
+    members: optedIn.map(
+      (member): ForecastMember => ({
+        riskBand: member.riskBand,
+        observability: member.activity.observability,
+        dailySurvival: member.dailySurvival,
+      }),
+    ),
+    pipeline: members
+      .filter((member) => member.state === "invited" || member.state === "accepted")
+      .map(
+        (member): PipelineMember => ({
+          stage: member.state === "accepted" ? "accepted" : "invited",
+          unreachable: member.unreachable,
+        }),
+      ),
+    optedInEver: members.filter((member) => member.estimatedOptedInAt !== null).length,
+    invitedEver: members.length,
+    // Derived exactly as `buildSnapshot` derives them. Hardcoding `null`/`0` here could never clear the
+    // forecast's five-conversion evidence gate, so every live read used the default three-day prior
+    // even for a cohort with a hundred measured conversions — while the snapshot written the same
+    // morning used the real one, and the two projected different completion dates.
+    ...conversionLatency(readings.map((entry) => entry.member)),
+    cohortAgeDays: cohortAgeDays(cohort.createdAt, today),
+    maxRosterSize: cohort.maxRosterSize,
+  });
+
+  const weakMemberCount = optedIn.filter(
+    (member) => member.riskBand === "at_risk" || member.riskBand === "critical",
+  ).length;
+
+  const latest = options.latest;
+  const trend: TrendView = {
+    // The direction comes off the stored snapshot rather than being recomputed here: the deltas it
+    // needs are historical, and recomputing them on read would give a card and a chart two different
+    // answers to the same question.
+    direction: latest?.trendDirection ?? "unknown",
+    reason: latest?.trendReason ?? "Not enough history yet.",
+    // All three conjuncts, matching `computeTrend` and both schema descriptions: at target, no
+    // headroom, AND at least one weak tester. Dropping the third made a twelve-of-twelve cohort of
+    // entirely healthy testers raise "One lapse from a reset." until its first snapshot landed, at
+    // which point the warning vanished with nothing about the cohort having changed.
+    fragile: latest?.fragile ?? (clock.meetsTarget && clock.headroom === 0 && weakMemberCount > 0),
+    optedInDelta1d: latest?.optedInDelta1d ?? null,
+    optedInDelta7d: latest?.optedInDelta7d ?? null,
+    activeDelta7d: latest?.activeDelta7d ?? null,
+    successProbabilityDelta7d: latest?.successProbabilityDelta7d ?? null,
+    series: options.snapshots.map(snapshotView),
+  };
+
+  return {
+    id: cohort.id,
+    name: cohort.name,
+    targetPlatform: cohort.targetPlatform,
+    targetSize: cohort.targetSize,
+    windowDays: cohort.windowDays,
+    maxRosterSize: cohort.maxRosterSize,
+    resetPolicy: cohort.resetPolicy,
+    createdAt: cohort.createdAt.toISOString(),
+    closedAt: iso(cohort.closedAt),
+
+    roster: {
+      size: members.length,
+      // Counted against the same live states `inviteMember` enforces the cap on. Counting `lapsed`
+      // members as occupying slots reported no room when an invitation would in fact have succeeded.
+      headroomToMax: Math.max(0, cohort.maxRosterSize - members.filter((m) => LIVE_STATES.includes(m.state)).length),
+      invited: byState("invited"),
+      accepted: byState("accepted"),
+      optedIn: optedIn.length,
+      lapsed: byState("lapsed") + byState("removed"),
+      unreachable: members.filter((member) => member.unreachable).length,
+      neverLinked: optedIn.filter((member) => member.activity.state === "never_linked").length,
+    },
+
+    estimatedClock: {
+      source: "pithy_estimate",
+      meetsTarget: clock.meetsTarget,
+      headroom: clock.headroom,
+      estimatedHeldDays: clock.estimatedHeldDays,
+      estimatedDaysRemaining: clock.estimatedDaysRemaining,
+      estimatedWindowStartOn: clock.estimatedWindowStartOn,
+      resetCount: clock.resetCount,
+      dayBoundary: "UTC",
+    },
+
+    activity: {
+      source: "observed",
+      active: observed.filter((member) => member.activity.state === "active").length,
+      darkThreeToSeven: observed.filter(
+        (m) => m.activity.daysDark !== null && m.activity.daysDark >= 3 && m.activity.daysDark <= 7,
+      ).length,
+      darkEightToThirteen: observed.filter(
+        (m) => m.activity.daysDark !== null && m.activity.daysDark >= 8 && m.activity.daysDark <= 13,
+      ).length,
+      darkFourteenPlus: observed.filter((m) => m.activity.daysDark !== null && m.activity.daysDark >= 14).length,
+      neverLinked: optedIn.filter((member) => member.activity.state === "never_linked").length,
+      observedCoverage: optedIn.length === 0 ? 0 : observed.length / optedIn.length,
+    },
+
+    projection: {
+      basis: forecast.basis,
+      calibration: forecast.calibration,
+      method: forecast.method,
+      confidence: forecast.confidence,
+      observedCoverage: forecast.observedCoverage,
+      probabilityReachTarget: forecast.probabilityReachTarget,
+      probabilityHoldWindow: forecast.probabilityHoldWindow,
+      successProbability: forecast.successProbability,
+      successProbabilityRange:
+        forecast.successProbabilityLow === null || forecast.successProbabilityHigh === null
+          ? null
+          : { low: forecast.successProbabilityLow, high: forecast.successProbabilityHigh },
+      expectedSurvivors: forecast.expectedSurvivors,
+      projectedTargetMetOn: forecast.projectedTargetMetOn,
+      projectedCompleteOn: forecast.projectedCompleteOn,
+      invitesNeeded: forecast.invitesNeeded,
+      recommendedRosterSize: forecast.recommendedRosterSize,
+    },
+
+    trend,
+
+    reconciliation: {
+      supported: false,
+      lastReconciledAt: null,
+      reason:
+        "The Google Play Developer API exposes no tester roster, no opt-in count, and no opt-out signal, so there is nothing to reconcile against.",
+    },
+
+    // Unconditional. There is no code path here that returns a cohort without it, which is the point:
+    // a note in the docs is advice, and a required field is a fact about the wire format.
+    disclaimer: DISCLAIMER,
+    ...(options.includeMembers ? { members } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add testers` wires into `pithy.config.ts`.
+ *
+ * Deliberately narrow: the capability factory and its type guard, the configuration schema, the four
+ * table schemas, and the two things a management client or the CLI needs by name — the control-plane
+ * scopes and the disclaimer every opt-in figure travels with. Every other module is reached by deep
+ * path (`@pithy-sh/testers/src/...`); this is the documented contract, not a barrel over the package.
+ *
+ * `workflows/worker.ts` is **not** here and must not be. It imports `cloudflare:workers`, and
+ * re-exporting it would make that import unresolvable in every Node context that touches this package —
+ * including the CLI, the seed harness, and every node-project test.
+ */
+
+export {
+  isTestersCapability,
+  TESTERS_MIGRATION_ORDER,
+  type TestersCapability,
+  type TestersOptions,
+  testers,
+} from "./capability";
+export {
+  CohortDefaults,
+  HealthCredits,
+  HealthPenalties,
+  NudgePolicy,
+  ResetPolicy,
+  SurvivalPriors,
+  TesterPlatform,
+  TestersConfig,
+  type TestersConfigInput,
+} from "./config/config";
+export { TestersCohort } from "./data/cohort";
+export {
+  ActivityState,
+  MemberEventKind,
+  MemberState,
+  NudgeKind,
+  Observability,
+  ProjectionBasis,
+  ProjectionConfidence,
+  RiskBand,
+  TrendDirection,
+} from "./data/enums";
+export { TestersEvent } from "./data/event";
+export { TestersMember } from "./data/member";
+export { TestersCohortSnapshot } from "./data/snapshot";
+export {
+  TESTERS_COHORTS_TABLE,
+  TESTERS_EVENTS_TABLE,
+  TESTERS_MEMBERS_TABLE,
+  TESTERS_SNAPSHOTS_TABLE,
+  type TestersDatabase,
+  testersDatabase,
+  testersTables,
+} from "./data/tables";
+export { DISCLAIMER, ESTIMATE_STATEMENT } from "./http/responses";
+export { TESTERS_ROUTES, type TestersRouteDeclaration } from "./http/routes";
+export {
+  TESTERS_CONTROL_PLANE_SCOPES,
+  TESTERS_NUDGE_SEND_SCOPE,
+  TESTERS_ROSTER_READ_SCOPE,
+  TESTERS_ROSTER_WRITE_SCOPE,
+} from "./http/scopes";
+export {
+  deprovisionTesters,
+  provisionTesters,
+  type TestersDeprovisioner,
+  type TestersProvisioner,
+  type TestersProvisionResult,
+  testersWorkerName,
+} from "./provision/provisionTesters";
+export {
+  resolveTestersConfig,
+  type TestersConfigParams,
+  type TestersEmailIdentity,
+} from "./provision/resolveTestersConfig";
+export { TESTERS_CAPABILITY, TestersDailyParams, testersWorkflowRegistry, testersWorkflows } from "./workflows/specs";