@pithy-sh/testers 0.1.0

package/src/data/enums.ts

@@ -0,0 +1,134 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The shared vocabulary of the roster: what state a tester is in, what moved them there, and how much
+ * of them we can actually see.
+ *
+ * **The naming rule this file exists to hold.** Anything derived from the opt-in event log is Pithy's
+ * estimate of a number Google owns and does not expose; anything derived from `@pithy-sh/auth` is
+ * observed fact. The two are never merged into a single "status", because a merged field would have to
+ * pick one authority and silently claim the other. `MemberState` is the estimate, `ActivityState` is the
+ * fact, and every member carries both.
+ */
+
+/**
+ * A tester's position on the roster.
+ *
+ * **Only four things write a transition, and inactivity is not one of them.** A tester who opted in and
+ * never opens the app still counts toward Google's twelve, so lapsing them for going quiet would turn
+ * Pithy's count from "our record of who confirmed" into "our guess dressed as a record" — and the
+ * divergence from Google would become unbounded and undetectable. Silence makes a tester look alarming
+ * in the health column. It never moves them off the count.
+ */
+export const MemberState = z
+  .enum(["invited", "accepted", "opted_in", "lapsed", "removed"])
+  .describe(
+    "Roster state, replayed from the event log: `invited` (we sent the invitation), `accepted` (they answered it — they have agreed to test, so their address is ready to go on the store's tester list), `opted_in` (they followed the link through to the store's own opt-in page, which is the closest thing to enrollment Pithy can observe), `lapsed` (they opted out), `removed` (the developer took them off). Inactivity never writes any of these, and neither does signing in — that is activity, not membership.",
+  );
+export type MemberState = z.output<typeof MemberState>;
+
+/**
+ * What happened to a member, as an append-only fact.
+ *
+ * The streak is replayed from these rather than stored as a counter, so a correction is a recomputation
+ * and the history survives it. That is also what lets a snapshot written last Tuesday stay an accurate
+ * record of what we believed last Tuesday.
+ */
+export const MemberEventKind = z
+  .enum(["invited", "reinvited", "accepted", "opted_in", "lapsed", "removed", "nudged"])
+  .describe(
+    "The event kinds the roster is replayed from. `reinvited` and `nudged` are recorded but do not change state — they are the outreach history the cooldown and the health score read.",
+  );
+export type MemberEventKind = z.output<typeof MemberEventKind>;
+
+/**
+ * Who or what caused an event.
+ *
+ * Worth storing because the same transition means different things depending on its author: a `lapsed`
+ * the tester wrote by following an opt-out link is a fact about them, while a `lapsed` the developer
+ * wrote is a fact about the roster.
+ */
+export const EventActor = z
+  .enum(["tester", "developer", "system"])
+  .describe(
+    "Who caused this event: the `tester` (they followed a link), the `developer` (a control-plane or CLI action), or the `system` (the daily pass).",
+  );
+export type EventActor = z.output<typeof EventActor>;
+
+/**
+ * How much of a tester we can see at all.
+ *
+ * This is a *different kind of statement* from a health score, which is why it gets its own field
+ * rather than a low number. A tester who opted in and never signed in is not evidence of risk; it is
+ * absence of evidence. Scoring them badly would paint a perfectly healthy cohort red the moment an
+ * adopter's test flow does not require a sign-in — and that is a common, legitimate app.
+ */
+export const Observability = z
+  .enum(["observed", "unobservable", "unreachable"])
+  .describe(
+    "Whether activity data exists for this tester: `observed` (their address matched a user with at least one session or device), `unobservable` (no match, or a match with no activity at all), `unreachable` (their address bounced or is suppressed, so we cannot even nudge them).",
+  );
+export type Observability = z.output<typeof Observability>;
+
+/**
+ * What the observed activity says, when there is any.
+ *
+ * `never_linked` is deliberately not a flavour of `inactive`. "Quiet since the 12th" is a tester
+ * drifting away; "never signed in" may simply be an app that does not ask anyone to sign in. A UI that
+ * renders them the same way will send nudges to people who did nothing wrong.
+ */
+export const ActivityState = z
+  .enum(["active", "inactive", "never_linked", "unreachable"])
+  .describe(
+    "Observed activity: `active` (authenticated inside the active window), `inactive` (matched a user but has gone quiet, with a date), `never_linked` (the invited address never matched a user, so there is no 'since'), `unreachable` (bounced or suppressed).",
+  );
+export type ActivityState = z.output<typeof ActivityState>;
+
+/** The health bands a score falls into, each selecting one published survival prior. */
+export const RiskBand = z
+  .enum(["healthy", "watch", "at_risk", "critical", "unknown"])
+  .describe(
+    "The band a tester's health score falls in, which selects their daily-survival prior. `unknown` is for a tester with no score at all — unobservable or unreachable — and must render gray rather than red.",
+  );
+export type RiskBand = z.output<typeof RiskBand>;
+
+/** Which nudge was sent. Each has shipped default copy and its own trigger in the daily pass. */
+export const NudgeKind = z
+  .enum(["confirm", "store", "inactive", "closing"])
+  .describe(
+    "The nudge kinds: `confirm` (will you help test?), `store` (you are on the list — here is the link to join and install), `inactive` (you have not opened the app recently), `closing` (the test window is nearly over). `confirm` and `store` are two messages rather than one because the store's opt-in page only works once the developer has added that address to the tester list, which no API can do — sending the link first produces `App not available` and a tester who thinks the app is broken. Every kind ships default copy, so `pithy testers run` chases sensibly with no dashboard involved.",
+  );
+export type NudgeKind = z.output<typeof NudgeKind>;
+
+/** Which way a cohort is heading, over the last week of snapshots. */
+export const TrendDirection = z
+  .enum(["improving", "steady", "declining", "unknown"])
+  .describe(
+    "Direction of travel across the trailing snapshots. `unknown` until three snapshots exist — a chart drawn from two points is a straight line through noise.",
+  );
+export type TrendDirection = z.output<typeof TrendDirection>;
+
+/**
+ * Why the projection reads the way it does — and, when a number is null, why there is no number.
+ *
+ * The null case is the one that matters. When nothing about a cohort is observable, the forecast is
+ * `null` and this says `no_observable_signal`, rather than a plausible-looking 0.5 that a dashboard
+ * would render as a real answer.
+ */
+export const ProjectionBasis = z
+  .enum(["estimated", "target_met", "insufficient_pipeline", "no_observable_signal", "no_history"])
+  .describe(
+    "Why the projection reads as it does: `estimated` (a normal forecast), `target_met` (already at target and holding), `insufficient_pipeline` (not enough pending invitations to close the gap at the observed conversion rate), `no_observable_signal` (nothing is observable, so the forecast is null rather than guessed), `no_history` (the cohort is too new to project).",
+  );
+export type ProjectionBasis = z.output<typeof ProjectionBasis>;
+
+/** How much to trust the forecast, driven by how much of the cohort we can see. */
+export const ProjectionConfidence = z
+  .enum(["low", "moderate", "high"])
+  .describe(
+    "Confidence in the forecast, driven by observability coverage and the cohort's age. Null rather than `low` when coverage is zero — 'we can see nothing' is not a weak opinion, it is no opinion.",
+  );
+export type ProjectionConfidence = z.output<typeof ProjectionConfidence>;

package/src/data/event.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { EventActor, MemberEventKind, NudgeKind } from "./enums";
+
+/** What a `nudged` event carries: which nudge went out, and the email job that carries it. */
+export const NudgeEventMetadata = z
+  .object({
+    nudgeKind: NudgeKind.describe("Which nudge was sent."),
+    jobId: z
+      .string()
+      .describe(
+        "The `pithy_email_jobs.id` this nudge became. The join back to delivery, bounces, and the copy that was actually sent.",
+      ),
+    copySource: z
+      .enum(["default", "supplied"])
+      .describe(
+        "Whether the words were this capability's shipped default or supplied by a control-plane caller. Recorded because a message sent over the adopter's own DKIM signature should be attributable to whoever wrote it.",
+      ),
+  })
+  .describe("Metadata carried by a `nudged` event — which nudge, which email job, and who wrote the words.");
+export type NudgeEventMetadata = z.output<typeof NudgeEventMetadata>;
+
+/** Anything an event may carry beyond its kind. Empty for most transitions. */
+export const EventMetadata = z
+  .object({
+    nudge: NudgeEventMetadata.optional().describe("Present on a `nudged` event; absent on every other kind."),
+    reason: z
+      .string()
+      .max(200)
+      .optional()
+      .describe("A short free-text reason a developer supplied when removing a tester. Never shown to the tester."),
+  })
+  .describe(
+    "Optional context on an event. Deliberately narrow — an event log that accepts arbitrary shapes stops being replayable.",
+  );
+export type EventMetadata = z.output<typeof EventMetadata>;
+
+/**
+ * One thing that happened to a tester — the append-only row in `pithy_testers_events`.
+ *
+ * **This table is the source of truth, and the streak is replayed from it rather than stored.** The
+ * design note in the issue asks for exactly this, and the reason is that a stored counter has no way to
+ * be wrong in public: if a member's opt-in date turns out to be mistaken, a counter can only be
+ * overwritten, losing both the old value and the fact that it changed. Replaying means a correction is
+ * an insert plus a recomputation, and every daily snapshot written before it stays a faithful record of
+ * what Pithy believed on that day — which is precisely what a trend chart is claiming to show.
+ *
+ * Rows are never updated and never deleted except by cohort teardown. `occurredAt` is the ordering key,
+ * not `id`: an event can be recorded late (an opt-in confirmed on a phone with a stale clock, a
+ * backfill) and replaying by insertion order would put it in the wrong day.
+ */
+export const TestersEvent = z
+  .object({
+    id: z
+      .number()
+      .int()
+      .describe("Primary key, auto-incrementing. Internal — an event id is never exposed or linked to."),
+    cohortId: z.string().describe("The cohort this event belongs to. Indexed with `occurredAt` for the replay scan."),
+    memberId: z
+      .string()
+      .describe("The member this event is about. Indexed — a per-tester replay reads only their rows."),
+    kind: MemberEventKind.describe("What happened."),
+    actor: EventActor.describe("Who caused it: the tester, the developer, or the daily pass."),
+    occurredAt: SQLiteDate.describe(
+      "When it happened — the replay's ordering key, not the insertion order. Ms-epoch in SQLite; a `Date` in app code.",
+    ),
+    metadata: sqliteJson(EventMetadata).describe(
+      "Context for this event, Zod-validated on write and on read. `{}` for a plain transition.",
+    ),
+    createdAt: SQLiteDate.describe(
+      "When the row was inserted. Differs from `occurredAt` for a backfilled event, which is how a late-recorded fact stays distinguishable from a timely one.",
+    ),
+  })
+  .describe(
+    "One append-only fact about a tester in `pithy_testers_events` — the source of truth the roster state and the estimated streak are both replayed from.",
+  );
+export type TestersEvent = z.output<typeof TestersEvent>;
+export type TestersEventRow = z.input<typeof TestersEvent>;

package/src/data/member.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { MemberState } from "./enums";
+
+/**
+ * One tester on one cohort's roster — the row in `pithy_testers_members`.
+ *
+ * **The state and its dates are a projection of the event log, never the source of truth.** They live
+ * here so the common reads — "who is on this roster", "who is due a nudge" — are one indexed query
+ * instead of a replay, but every one of them is rebuilt from `pithy_testers_events` by
+ * `replayMember`. If the two ever disagree, the events win and the projection is wrong. That is the
+ * whole reason a correction to history is a recomputation rather than an argument.
+ *
+ * **The email address is the join key to `@pithy-sh/auth`, and it is stored lowercased.** A tester is
+ * invited by address and becomes visible only when they sign in with it; matching is exact, because
+ * auth's `email` column is unique and every Pithy sign-in is provider-verified. No `userId` is stored:
+ * caching it would create a second thing to keep in step, and the lookup is a single indexed hit.
+ */
+export const TestersMember = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        "The member's UUID. Text rather than a sequential integer because it appears in control-plane responses and in the audit trail, and a countable id there tells a reader how large the roster is and lets them address rows they were never handed. The opt-in links carry `optInToken`, not this.",
+      ),
+    cohortId: z.string().describe("The cohort this member belongs to. Indexed — every roster read starts here."),
+    email: z
+      .string()
+      .describe(
+        "The invited address, lowercased. The join key to `pithy_auth_users.email`, and the address every invitation and nudge is sent to. Unique per cohort.",
+      ),
+    name: z.string().nullable().describe("A display name the developer supplied when inviting, or null."),
+    optInToken: z
+      .string()
+      .describe(
+        "The tester's confirmation credential — 32 bytes of CSPRNG, base64url. The token IS the credential, as with `@pithy-sh/storage`'s share links: it is looked up on every visit, which is what makes it revocable where a signed token could only expire. Generated when the row is created, so nothing has to be minted at send time and no secret is needed to build an invitation in any environment. Unique across the table.",
+      ),
+    state: MemberState.describe(
+      "The member's current roster state, projected from the event log. Never written by inactivity — a quiet tester is still opted in.",
+    ),
+    invitedAt: SQLiteDate.describe(
+      "When the first invitation was sent. Every member has one; it is how they got here.",
+    ),
+    acceptedAt: SQLiteDate.nullable().describe(
+      "When they answered the first email saying they will test, or null. Consent, not enrollment: it is a tap on a link, needs no account, and proves nothing about installing or opting in at the store — that is `optedInAt`.",
+    ),
+    optedInAt: SQLiteDate.nullable().describe(
+      "When they followed Pithy's confirmation link, or null. PITHY'S ESTIMATE of their opt-in date — it records that they clicked our link, not that Google recorded an opt-in. The two can differ and no API exposes Google's.",
+    ),
+    lapsedAt: SQLiteDate.nullable().describe(
+      "When they opted out or were removed, or null. Written only by an explicit act — never by going quiet.",
+    ),
+    lastInvitedAt: SQLiteDate.describe(
+      "When an invitation was most recently sent, including resends. Distinct from `invitedAt` so the streak still measures from the first contact.",
+    ),
+    lastNudgedAt: SQLiteDate.nullable().describe(
+      "When a nudge was most recently enqueued for this tester, or null. The cooldown reads this, and it is written at enqueue rather than at delivery: a cooldown that waited for the send Workflow would let a retried request mail twice.",
+    ),
+    nudgeCount: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe(
+        "How many nudges have been enqueued since this tester last answered one. Cleared when they accept the invitation or confirm the opt-in, so it measures unanswered probes rather than lifetime volume. Feeds the health score's unanswered-probe penalty and the cap that stops chasing after three.",
+      ),
+    unreachable: SQLiteBoolean.describe(
+      "Whether this address hard-bounced or is suppressed. SQLite has no boolean, so the column is `0`/`1` and the codec is the only place that conversion happens — it carried a hand-written integer and a rationale about summing it in SQL, and no SQL anywhere sums it: every count is a filter over already-decoded rows.",
+    ),
+    createdAt: SQLiteDate.describe("When the member row was created."),
+    updatedAt: SQLiteDate.describe("When the member row was last written."),
+  })
+  .describe(
+    "One tester on one cohort in `pithy_testers_members` — a projection of the event log, kept for cheap reads. Every opt-in figure on it is Pithy's estimate; Google's equivalent is not readable.",
+  );
+export type TestersMember = z.output<typeof TestersMember>;
+export type TestersMemberRow = z.input<typeof TestersMember>;

package/src/data/snapshot.ts

@@ -0,0 +1,280 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { ProjectionBasis, ProjectionConfidence, TrendDirection } from "./enums";
+
+/** A day-key: `YYYY-MM-DD`, UTC. */
+const DAY_KEY = /^\d{4}-\d{2}-\d{2}$/;
+
+/** How many nudges of each kind went out on one day. */
+export const NudgeTally = z
+  .object({
+    confirm: z.number().int().describe("Will-you-test nudges enqueued on this day — the first email of the two."),
+    store: z
+      .number()
+      .int()
+      .describe(
+        "Store-link nudges enqueued on this day — the second email, and the only one that can move the opt-in count, because it is the one carrying the link that joins the test.",
+      ),
+    inactive: z.number().int().describe("You-have-not-opened-the-app nudges enqueued on this day."),
+    closing: z.number().int().describe("The-window-is-closing nudges enqueued on this day."),
+  })
+  .describe("Nudges enqueued on this day, by kind, so send volume can be charted against the health series.");
+export type NudgeTally = z.output<typeof NudgeTally>;
+
+/**
+ * One day of a cohort's position — the row in `pithy_testers_cohort_snapshots`, and the chartable
+ * record the whole dashboard trend is drawn from.
+ *
+ * **Why a snapshot table exists at all, when everything in it is derivable.** Two reasons, and the
+ * second is the load-bearing one. First, cost: a summary card should be one row, not a replay of every
+ * event plus a join against auth. Second, and more important, **activity is not derivable
+ * retroactively**. Sessions expire and rotate, devices are re-registered, and a tester who was quiet on
+ * the 9th but active on the 11th leaves no trace on the 12th that they were ever quiet. The opt-in
+ * clock can always be replayed; the early-warning signal cannot. If it is not written down on the day,
+ * it is gone — which is exactly why the darkness histogram, the thing that moves *before* the opt-in
+ * count does, has to be captured daily rather than computed on read.
+ *
+ * **Every field is one of two kinds and the names say which.** Anything prefixed `estimated` is Pithy's
+ * replay of its own invite records — its best guess at a figure Google computes and exposes through no
+ * API. Everything under the activity block is observed fact from `@pithy-sh/auth`. A field that blurred
+ * the two would be the single most damaging thing this package could ship, because a developer reading
+ * `heldDays: 13` and planning to apply for production access tomorrow is making a decision on it.
+ *
+ * The day key is UTC and stored as `YYYY-MM-DD` **text**, not a timestamp: day arithmetic and the
+ * unique index are then exact, with no timezone in the query. Google's own day boundary is undocumented
+ * and may not be ours, which is one more reason day fourteen is the wrong day to start trusting this.
+ */
+export const TestersCohortSnapshot = z
+  .object({
+    id: z
+      .number()
+      .int()
+      .describe("Primary key, auto-incrementing. Internal — a snapshot is addressed by cohort and day."),
+    cohortId: z.string().describe("The cohort this snapshot describes. Unique with `snapshotOn`."),
+    snapshotOn: z
+      .string()
+      .regex(DAY_KEY)
+      .describe("The UTC day this snapshot covers, `YYYY-MM-DD`. The chart's x-axis, and half of the row's identity."),
+    dayIndex: z
+      .number()
+      .int()
+      .describe("Days since the cohort was created — a zero-based x-axis, so two cohorts can be overlaid."),
+    computedAt: SQLiteDate.describe("When the daily pass computed this row."),
+    backfilled: SQLiteBoolean.describe(
+      "True when this row was written after its day had already passed — a missed run, or a replay. Charts must render a backfilled point dashed: the opt-in figures are still exact, but the activity figures were reconstructed from whatever survived, and are therefore a floor rather than a measurement.",
+    ),
+    modelVersion: z
+      .string()
+      .describe(
+        "The survival and health constant set that produced this row's forecast. A trend line silently spanning two model versions is a lie; the chart annotates where it changes.",
+      ),
+
+    // — roster composition: a stacked area falls out of these five —
+    rosterSize: z.number().int().describe("Members on the roster on this day, in every state."),
+    invitedCount: z.number().int().describe("Invited, and have not yet answered the first email."),
+    acceptedCount: z.number().int().describe("Agreed to test on this day, and waiting for the store link."),
+    estimatedOptedInCount: z
+      .number()
+      .int()
+      .describe(
+        "PITHY'S ESTIMATE of how many testers were opted in on this day, replayed from the confirmation-link records. Google's authoritative count is not readable by any API.",
+      ),
+    lapsedCount: z.number().int().describe("Explicitly opted out or removed. Never written by inactivity."),
+    unreachableCount: z
+      .number()
+      .int()
+      .describe("Hard-bounced or suppressed in `@pithy-sh/email` — we cannot even nudge them."),
+
+    // — the clock, entirely Pithy's estimate —
+    targetSize: z
+      .number()
+      .int()
+      .describe("The target in force on this day, denormalized so a later change cannot rewrite history."),
+    windowDays: z.number().int().describe("The window in force on this day, denormalized for the same reason."),
+    meetsTarget: SQLiteBoolean.describe("Whether the estimated opted-in count reached the target on this day."),
+    headroom: z
+      .number()
+      .int()
+      .describe(
+        "Estimated opted-in count minus target. Charts as a signed series where zero is the danger line, and it can go negative.",
+      ),
+    estimatedHeldDays: z
+      .number()
+      .int()
+      .describe(
+        "Pithy's estimate of the unbroken run of at-target days ending on this day. The number Play Console shows, as far as we can infer it.",
+      ),
+    estimatedWindowStartOn: z
+      .string()
+      .regex(DAY_KEY)
+      .nullable()
+      .describe("The UTC day the current run began, or null while below target."),
+    estimatedDaysRemaining: z
+      .number()
+      .int()
+      .describe("Window days still to hold, on Pithy's estimate, floored at zero."),
+    resetCount: z
+      .number()
+      .int()
+      .describe(
+        "How many times the run has broken since the cohort started. Scar tissue, and it belongs on the chart.",
+      ),
+    resetToday: SQLiteBoolean.describe(
+      "Whether the run broke on this day — the single most important annotation a cohort chart can carry.",
+    ),
+
+    // — activity: observed fact from @pithy-sh/auth —
+    observedCount: z
+      .number()
+      .int()
+      .describe("Opted-in members whose address matched a user with at least one session or device."),
+    neverLinkedCount: z
+      .number()
+      .int()
+      .describe(
+        "Opted-in members whose invited address never matched a user. They still count toward the target — an app whose test flow needs no sign-in produces nothing else — and they must render differently from inactive.",
+      ),
+    observedCoverage: z
+      .number()
+      .min(0)
+      .max(1)
+      .describe(
+        "Observed count over opted-in count, 0–1. The honest denominator behind every forecast number on this row.",
+      ),
+    activeCount: z.number().int().describe("Observed members who authenticated inside the cohort's active window."),
+    darkThreeToSevenCount: z.number().int().describe("Observed members quiet 3–7 days. The first leading indicator."),
+    darkEightToThirteenCount: z
+      .number()
+      .int()
+      .describe("Observed members quiet 8–13 days. The strongest silent-uninstall signal."),
+    darkFourteenPlusCount: z.number().int().describe("Observed members quiet 14 days or more."),
+    sessionsInWindow: z.number().int().describe("Total sessions across the cohort inside the trailing window."),
+    targetPlatformDeviceCount: z
+      .number()
+      .int()
+      .describe("Members with at least one registered device on the cohort's target platform."),
+
+    // — health distribution —
+    healthyCount: z.number().int().describe("Observed members scoring 80–100."),
+    watchCount: z.number().int().describe("Observed members scoring 60–79."),
+    atRiskCount: z.number().int().describe("Observed members scoring 30–59."),
+    criticalCount: z.number().int().describe("Observed members scoring 0–29."),
+    unknownHealthCount: z.number().int().describe("Members with no score at all — unobservable or unreachable."),
+    medianHealth: z
+      .number()
+      .int()
+      .nullable()
+      .describe("Median health across observed members, or null when none are observed."),
+    minHealth: z
+      .number()
+      .int()
+      .nullable()
+      .describe(
+        "The weakest observed member's score, or null. A twelve-of-twelve cohort breaks at its weakest link, so the minimum matters more than the mean.",
+      ),
+
+    // — the forecast, as of this day —
+    expectedSurvivors: z
+      .number()
+      .describe(
+        "Sum of each opted-in tester's chance of lasting the remaining days — 'we expect 11.3 of your 14 to still be in'.",
+      ),
+    probabilityReachTarget: z.number().describe("Chance of reaching the target at all. One when already there."),
+    probabilityHoldWindow: z
+      .number()
+      .nullable()
+      .describe(
+        "Chance at least `targetSize` testers hold for the remaining days. Null when nothing about the cohort is observable.",
+      ),
+    successProbability: z
+      .number()
+      .min(0)
+      .max(1)
+      .nullable()
+      .describe(
+        "PITHY'S ESTIMATE of completing the window: reach times hold. Capped below one — nothing is certain until Google says so, and Google is not talking. Null when there is no observable signal at all.",
+      ),
+    successProbabilityLow: z
+      .number()
+      .min(0)
+      .max(1)
+      .nullable()
+      .describe("The pessimistic bound, treating every unobservable tester as fragile."),
+    successProbabilityHigh: z
+      .number()
+      .min(0)
+      .max(1)
+      .nullable()
+      .describe("The optimistic bound, treating every unobservable tester as solid."),
+    confidence: ProjectionConfidence.nullable().describe("How much to trust the forecast. Null when coverage is zero."),
+    basis: ProjectionBasis.describe("Why the forecast reads as it does, and why any null on this row is null."),
+    projectedTargetMetOn: z
+      .string()
+      .regex(DAY_KEY)
+      .nullable()
+      .describe("Projected UTC day the cohort first reaches target, or null with a basis."),
+    projectedCompleteOn: z
+      .string()
+      .regex(DAY_KEY)
+      .nullable()
+      .describe("Projected UTC day the window completes, or null with a basis."),
+    invitesNeeded: z
+      .number()
+      .int()
+      .describe(
+        "How many more people to invite to close the gap at the observed conversion rate. Zero when at target. Worth more to a developer than the probability next to it.",
+      ),
+    recommendedRosterSize: z
+      .number()
+      .int()
+      .describe(
+        "The roster size that survives the window at this cohort's own conversion and drop-off rates. The over-provisioning answer.",
+      ),
+
+    // — the trend, precomputed so one row renders a whole card —
+    optedInDelta1d: z
+      .number()
+      .int()
+      .nullable()
+      .describe("Change in the estimated opted-in count since yesterday. Null without a prior snapshot."),
+    optedInDelta7d: z
+      .number()
+      .int()
+      .nullable()
+      .describe("Change over seven days. Null without a snapshot seven days back."),
+    activeDelta7d: z
+      .number()
+      .int()
+      .nullable()
+      .describe("Change in the active count over seven days — engagement's direction."),
+    successProbabilityDelta1d: z.number().nullable().describe("Change in the forecast since yesterday."),
+    successProbabilityDelta7d: z
+      .number()
+      .nullable()
+      .describe("Change in the forecast over seven days. The trend rule's primary input."),
+    trendDirection: TrendDirection.describe(
+      "Improving, steady, declining, or unknown — by a published rule, not a fit.",
+    ),
+    fragile: SQLiteBoolean.describe(
+      "At target, with zero headroom, and at least one at-risk or critical member: one lapse from a reset. Deliberately not a trend direction — a cohort can be improving and fragile at once, and collapsing them loses the more urgent of the two.",
+    ),
+    trendReason: z
+      .string()
+      .describe(
+        "One brand-voice sentence explaining the direction, for rendering beside the arrow. E.g. `Two testers went dark this week.`",
+      ),
+
+    // — operations —
+    nudgesSent: sqliteJson(NudgeTally).describe(
+      "Nudges enqueued on this day, by kind. Overlays the health series so an intervention can be read against its effect.",
+    ),
+    bouncedCount: z.number().int().describe("Addresses newly found unreachable on this day."),
+  })
+  .describe(
+    "One day of a cohort's position in `pithy_testers_cohort_snapshots` — the chartable trend record the daily pass writes. Every opt-in figure here is Pithy's estimate from its own invite records; every activity figure is observed fact.",
+  );
+export type TestersCohortSnapshot = z.output<typeof TestersCohortSnapshot>;
+export type TestersCohortSnapshotRow = z.input<typeof TestersCohortSnapshot>;

package/src/data/tables.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { TestersCohort } from "./cohort";
+import { TestersEvent } from "./event";
+import { TestersMember } from "./member";
+import { TestersCohortSnapshot } from "./snapshot";
+
+/** The cohort itself. `CamelCasePlugin` snake-cases it to `pithy_testers_cohorts`. */
+export const TESTERS_COHORTS_TABLE = "pithyTestersCohorts";
+/** The roster projection. → `pithy_testers_members`. */
+export const TESTERS_MEMBERS_TABLE = "pithyTestersMembers";
+/** The append-only source of truth the streak is replayed from. → `pithy_testers_events`. */
+export const TESTERS_EVENTS_TABLE = "pithyTestersEvents";
+/** One row per cohort per UTC day — the chartable trend. → `pithy_testers_cohort_snapshots`. */
+export const TESTERS_SNAPSHOTS_TABLE = "pithyTestersCohortSnapshots";
+
+/** The testers tables map. All four are always present — none is behind a config flag. */
+export function testersTables(): Record<string, z.ZodObject> {
+  return {
+    [TESTERS_COHORTS_TABLE]: TestersCohort,
+    [TESTERS_MEMBERS_TABLE]: TestersMember,
+    [TESTERS_EVENTS_TABLE]: TestersEvent,
+    [TESTERS_SNAPSHOTS_TABLE]: TestersCohortSnapshot,
+  };
+}
+
+/** The typed Kysely database over the testers tables. */
+export type TestersTables = {
+  [TESTERS_COHORTS_TABLE]: typeof TestersCohort;
+  [TESTERS_MEMBERS_TABLE]: typeof TestersMember;
+  [TESTERS_EVENTS_TABLE]: typeof TestersEvent;
+  [TESTERS_SNAPSHOTS_TABLE]: typeof TestersCohortSnapshot;
+};
+export type TestersDatabase = Kysely<DatabaseSchema<TestersTables>>;
+
+/** Build the testers database from a D1 binding, with `CamelCasePlugin` installed. */
+export function testersDatabase(d1: D1Database): TestersDatabase {
+  return createDatabase(d1, {
+    [TESTERS_COHORTS_TABLE]: TestersCohort,
+    [TESTERS_MEMBERS_TABLE]: TestersMember,
+    [TESTERS_EVENTS_TABLE]: TestersEvent,
+    [TESTERS_SNAPSHOTS_TABLE]: TestersCohortSnapshot,
+  }) as unknown as TestersDatabase;
+}