@pithy-sh/testers 0.1.0

package/src/migrations/0001_cohorts.ts

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * The four testers tables: the cohort, its roster, the append-only event log the roster is replayed
+ * from, and the daily snapshot the trend chart is drawn from.
+ *
+ * Identifiers are camelCase throughout — `CamelCasePlugin` snake-cases the DDL. Dates are `integer`
+ * ms-epoch, booleans are `integer` 0/1, JSON columns are `text`.
+ *
+ * **Shape and value rules live in the Zod schemas, not here.** One Zod object per table is the entire
+ * table definition (CLAUDE.md §Data layer), so an enum's members, a number's bounds, a boolean's 0/1
+ * and the one cross-field rule (`maxRosterSize >= targetSize`) are all declared and enforced there —
+ * on `parse` *and* on `encode`, which is the boundary every write already crosses. Restating them as
+ * `CHECK` constraints bought a second source of truth that could drift from the first, and produced a
+ * raw `CHECK constraint failed` out of Kysely instead of a `PithyError` with an action line — no help
+ * to a human and no `--json` error object for an agent.
+ *
+ * What stays is what Zod cannot express, because it is a fact about the table rather than about a row:
+ * `UNIQUE` (a cohort name, a member's address within a cohort, a token, one snapshot per cohort-day)
+ * and the indexes the queries actually use.
+ *
+ * No foreign keys, matching the rest of the repo: D1 does not enforce them, so declaring them would be
+ * documentation pretending to be a constraint. Referential integrity is held by the writers, and cohort
+ * teardown deletes children first.
+ */
+export const testers_0001_cohorts: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyTestersCohorts")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("name", "text", (c) => c.notNull())
+      .addColumn("targetPlatform", "text", (c) => c.notNull())
+      .addColumn("targetSize", "integer", (c) => c.notNull())
+      .addColumn("windowDays", "integer", (c) => c.notNull())
+      .addColumn("maxRosterSize", "integer", (c) => c.notNull())
+      .addColumn("storeOptInUrl", "text")
+      .addColumn("resetPolicy", "text", (c) => c.notNull())
+      .addColumn("closedAt", "integer")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .addUniqueConstraint("pithyTestersCohortsNameIdx", ["name"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyTestersMembers")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("cohortId", "text", (c) => c.notNull())
+      .addColumn("email", "text", (c) => c.notNull())
+      .addColumn("name", "text")
+      .addColumn("optInToken", "text", (c) => c.notNull())
+      .addColumn("state", "text", (c) => c.notNull())
+      .addColumn("invitedAt", "integer", (c) => c.notNull())
+      .addColumn("acceptedAt", "integer")
+      .addColumn("optedInAt", "integer")
+      .addColumn("lapsedAt", "integer")
+      .addColumn("lastInvitedAt", "integer", (c) => c.notNull())
+      .addColumn("lastNudgedAt", "integer")
+      .addColumn("nudgeCount", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("unreachable", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      // One address per cohort. This is what makes an invitation idempotent at the storage layer rather
+      // than only in the handler: two concurrent invites of the same person cannot both land and split
+      // one tester's history across two rows, which would double-count them toward the target.
+      .addUniqueConstraint("pithyTestersMembersCohortEmailIdx", ["cohortId", "email"])
+      // The confirmation token is the whole credential, so it is unique across every cohort rather than
+      // within one: a collision would let one tester's link confirm another's opt-in.
+      .addUniqueConstraint("pithyTestersMembersOptInTokenIdx", ["optInToken"])
+      .execute();
+
+    // The roster read: every live member of one cohort, ordered by state. Covers the common
+    // "who is on this cohort" query without touching the event log.
+    await db.schema
+      .createIndex("pithyTestersMembersCohortStateIdx")
+      .on("pithyTestersMembers")
+      .columns(["cohortId", "state"])
+      .execute();
+
+    // The activity reader resolves testers by address across every cohort at once, so the daily pass
+    // does one lookup per distinct address rather than one per membership.
+    await db.schema.createIndex("pithyTestersMembersEmailIdx").on("pithyTestersMembers").column("email").execute();
+
+    await db.schema
+      .createTable("pithyTestersEvents")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("cohortId", "text", (c) => c.notNull())
+      .addColumn("memberId", "text", (c) => c.notNull())
+      .addColumn("kind", "text", (c) => c.notNull())
+      .addColumn("actor", "text", (c) => c.notNull())
+      .addColumn("occurredAt", "integer", (c) => c.notNull())
+      .addColumn("metadata", "text", (c) => c.notNull())
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    // The cohort-wide replay: every event for one cohort in `occurredAt` order. Ordering on the index
+    // rather than in memory matters because the replay walks the whole history to rebuild the streak.
+    await db.schema
+      .createIndex("pithyTestersEventsCohortTimeIdx")
+      .on("pithyTestersEvents")
+      .columns(["cohortId", "occurredAt"])
+      .execute();
+
+    // The per-tester replay, and the nudge-history read the cooldown and the health score both use.
+    await db.schema
+      .createIndex("pithyTestersEventsMemberTimeIdx")
+      .on("pithyTestersEvents")
+      .columns(["memberId", "occurredAt"])
+      .execute();
+
+    await db.schema
+      .createTable("pithyTestersCohortSnapshots")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("cohortId", "text", (c) => c.notNull())
+      .addColumn("snapshotOn", "text", (c) => c.notNull())
+      .addColumn("dayIndex", "integer", (c) => c.notNull())
+      .addColumn("computedAt", "integer", (c) => c.notNull())
+      .addColumn("backfilled", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("modelVersion", "text", (c) => c.notNull())
+      .addColumn("rosterSize", "integer", (c) => c.notNull())
+      .addColumn("invitedCount", "integer", (c) => c.notNull())
+      .addColumn("acceptedCount", "integer", (c) => c.notNull())
+      .addColumn("estimatedOptedInCount", "integer", (c) => c.notNull())
+      .addColumn("lapsedCount", "integer", (c) => c.notNull())
+      .addColumn("unreachableCount", "integer", (c) => c.notNull())
+      .addColumn("targetSize", "integer", (c) => c.notNull())
+      .addColumn("windowDays", "integer", (c) => c.notNull())
+      .addColumn("meetsTarget", "integer", (c) => c.notNull())
+      .addColumn("headroom", "integer", (c) => c.notNull())
+      .addColumn("estimatedHeldDays", "integer", (c) => c.notNull())
+      .addColumn("estimatedWindowStartOn", "text")
+      .addColumn("estimatedDaysRemaining", "integer", (c) => c.notNull())
+      .addColumn("resetCount", "integer", (c) => c.notNull())
+      .addColumn("resetToday", "integer", (c) => c.notNull())
+      .addColumn("observedCount", "integer", (c) => c.notNull())
+      .addColumn("neverLinkedCount", "integer", (c) => c.notNull())
+      .addColumn("observedCoverage", "real", (c) => c.notNull())
+      .addColumn("activeCount", "integer", (c) => c.notNull())
+      .addColumn("darkThreeToSevenCount", "integer", (c) => c.notNull())
+      .addColumn("darkEightToThirteenCount", "integer", (c) => c.notNull())
+      .addColumn("darkFourteenPlusCount", "integer", (c) => c.notNull())
+      .addColumn("sessionsInWindow", "integer", (c) => c.notNull())
+      .addColumn("targetPlatformDeviceCount", "integer", (c) => c.notNull())
+      .addColumn("healthyCount", "integer", (c) => c.notNull())
+      .addColumn("watchCount", "integer", (c) => c.notNull())
+      .addColumn("atRiskCount", "integer", (c) => c.notNull())
+      .addColumn("criticalCount", "integer", (c) => c.notNull())
+      .addColumn("unknownHealthCount", "integer", (c) => c.notNull())
+      .addColumn("medianHealth", "integer")
+      .addColumn("minHealth", "integer")
+      .addColumn("expectedSurvivors", "real", (c) => c.notNull())
+      .addColumn("probabilityReachTarget", "real", (c) => c.notNull())
+      .addColumn("probabilityHoldWindow", "real")
+      .addColumn("successProbability", "real")
+      .addColumn("successProbabilityLow", "real")
+      .addColumn("successProbabilityHigh", "real")
+      .addColumn("confidence", "text")
+      .addColumn("basis", "text", (c) => c.notNull())
+      .addColumn("projectedTargetMetOn", "text")
+      .addColumn("projectedCompleteOn", "text")
+      .addColumn("invitesNeeded", "integer", (c) => c.notNull())
+      .addColumn("recommendedRosterSize", "integer", (c) => c.notNull())
+      .addColumn("optedInDelta1d", "integer")
+      .addColumn("optedInDelta7d", "integer")
+      .addColumn("activeDelta7d", "integer")
+      .addColumn("successProbabilityDelta1d", "real")
+      .addColumn("successProbabilityDelta7d", "real")
+      .addColumn("trendDirection", "text", (c) => c.notNull())
+      .addColumn("fragile", "integer", (c) => c.notNull())
+      .addColumn("trendReason", "text", (c) => c.notNull())
+      .addColumn("nudgesSent", "text", (c) => c.notNull())
+      .addColumn("bouncedCount", "integer", (c) => c.notNull())
+      // One row per cohort per UTC day. This is what makes the daily pass idempotent: a re-run — a
+      // retried Workflow step, a manual backfill, two crons firing on a leap second — upserts the day
+      // rather than appending a second version of it, so a replay can never bend the chart.
+      .addUniqueConstraint("pithyTestersSnapshotsCohortDayIdx", ["cohortId", "snapshotOn"])
+      .execute();
+
+    // The trailing-series read: the last N days of one cohort, newest first. The summary card reads one
+    // row from the head of this index, which is what keeps the default response cheap.
+    await db.schema
+      .createIndex("pithyTestersSnapshotsCohortRecentIdx")
+      .on("pithyTestersCohortSnapshots")
+      .columns(["cohortId", "snapshotOn"])
+      .execute();
+  },
+
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyTestersSnapshotsCohortRecentIdx").execute();
+    await db.schema.dropTable("pithyTestersCohortSnapshots").execute();
+    await db.schema.dropIndex("pithyTestersEventsMemberTimeIdx").execute();
+    await db.schema.dropIndex("pithyTestersEventsCohortTimeIdx").execute();
+    await db.schema.dropTable("pithyTestersEvents").execute();
+    await db.schema.dropIndex("pithyTestersMembersEmailIdx").execute();
+    await db.schema.dropIndex("pithyTestersMembersCohortStateIdx").execute();
+    await db.schema.dropTable("pithyTestersMembers").execute();
+    await db.schema.dropTable("pithyTestersCohorts").execute();
+  },
+};

package/src/nudge/cooldown.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { TestersMember } from "../data/member";
+
+/**
+ * The per-tester nudge cooldown.
+ *
+ * **Mandatory, server-side, and on every path.** A nudge trigger with no guard is a button that mails
+ * the same twelve people repeatedly, and the fastest way to lose a cohort is to become the reason they
+ * muted the sender. The dashboard cannot be trusted to hold the line here — not because it is
+ * malicious, but because a retried request, a double-clicked button, and a cron that overlaps its own
+ * previous run all produce the same duplicate send, and none of them is a bug anyone would notice
+ * before the testers did.
+ *
+ * The cooldown reads `lastNudgedAt`, which is stamped at **enqueue** rather than at delivery. That is
+ * the ordering that makes the guard actually hold: waiting for the send Workflow to confirm would leave
+ * a window in which a second request sees no recent nudge and mails again. An email enqueued and then
+ * failing to send is a delivery problem; an email sent twice is a lost tester.
+ */
+
+/** Milliseconds in one hour. */
+const MS_PER_HOUR = 3_600_000;
+
+/** When a tester may next be nudged, or null if they may be nudged now. */
+export function cooldownUntil(member: TestersMember, cooldownHours: number): Date | null {
+  if (!member.lastNudgedAt) return null;
+  return new Date(member.lastNudgedAt.getTime() + cooldownHours * MS_PER_HOUR);
+}
+
+/** Whether this tester may be nudged right now. */
+export function mayNudge(member: TestersMember, cooldownHours: number, now: Date): boolean {
+  const until = cooldownUntil(member, cooldownHours);
+  return until === null || until <= now;
+}
+
+/**
+ * How many unanswered nudges a tester takes before we stop.
+ *
+ * The cooldown bounds how *often* somebody is mailed; this bounds how *many times*. The counter resets
+ * the moment they answer, so it only ever bites the genuinely unresponsive — who stay on the roster and
+ * stay visible, they simply stop being chased. Without it a tester who never replies is mailed every
+ * three days for the life of the cohort.
+ *
+ * It lives here rather than in the daily pass because the pass is not the only sender. It was read by
+ * `dueNudge` alone, so a dashboard holding `testers:nudge:send` could chase an unresponsive address
+ * indefinitely — the very thing https://pithy.sh/docs/capabilities/testers/use says cannot happen. The same reasoning that makes the
+ * cooldown re-enforced inside every handler applies to the cap.
+ */
+export const MAX_UNANSWERED_NUDGES = 3;
+
+/** Whether this tester has stopped answering and should no longer be chased. */
+export function chasedOut(member: TestersMember): boolean {
+  return member.nudgeCount >= MAX_UNANSWERED_NUDGES;
+}
+
+/** A roster split into who may be nudged and who is still cooling down. */
+export interface CooldownSplit {
+  readonly eligible: readonly TestersMember[];
+  readonly cooling: readonly TestersMember[];
+  readonly unreachable: readonly TestersMember[];
+  /** Testers who have stopped answering. Separate again, because this one never resolves with time. */
+  readonly chasedOut: readonly TestersMember[];
+}
+
+/**
+ * Split a set of testers by whether they may be nudged.
+ *
+ * Unreachable testers are separated rather than merged into `cooling`, because the two call for
+ * different actions: a cooling tester will be nudgeable tomorrow, while an unreachable one never will
+ * be and needs replacing. A response that reported them together would tell a developer to wait for
+ * something that is not going to happen.
+ */
+export function splitByCooldown(members: readonly TestersMember[], cooldownHours: number, now: Date): CooldownSplit {
+  const eligible: TestersMember[] = [];
+  const cooling: TestersMember[] = [];
+  const unreachable: TestersMember[] = [];
+  const exhausted: TestersMember[] = [];
+  for (const member of members) {
+    if (member.unreachable) unreachable.push(member);
+    else if (chasedOut(member)) exhausted.push(member);
+    else if (mayNudge(member, cooldownHours, now)) eligible.push(member);
+    else cooling.push(member);
+  }
+  return { eligible, cooling, unreachable, chasedOut: exhausted };
+}
+
+/**
+ * Whether this nudge answers something the tester just did, and so should not wait for the cooldown.
+ *
+ * **The cooldown exists to stop repeated chasing, not to delay a reply.** A tester who has just agreed
+ * to test and is waiting for the link is not being chased — they are waiting on us. Holding that email
+ * for three days because we happened to ask them two days ago is how a cohort loses the people who were
+ * most willing, and it is the single most avoidable way this capability could fail.
+ *
+ * The test is that their acceptance is newer than our last message to them. That needs no extra column
+ * and no second query: if we have not written to them since they said yes, this is the reply. Once it
+ * has gone, `lastNudgedAt` moves past `acceptedAt` and every later reminder falls under the normal
+ * cooldown like anything else.
+ */
+export function answersRecentAction(member: TestersMember): boolean {
+  if (!member.acceptedAt) return false;
+  return !member.lastNudgedAt || member.acceptedAt > member.lastNudgedAt;
+}

package/src/nudge/copy.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { NudgeKind } from "../data/enums";
+
+/**
+ * The words a nudge goes out with.
+ *
+ * **Two messages, not one, and the reason is external.** A tester's store opt-in page only works once
+ * the developer has added that address to the tester list — and no API can do that, so it is a manual
+ * step in the console. Sending the store link before it completes produces `App not available`, which
+ * reads to the tester as a broken app. So `confirm` asks whether they will help, and `store` follows
+ * once they are actually on the list.
+ *
+ * **Every kind ships serviceable default copy, and that is a requirement rather than a courtesy.** A
+ * developer with no dashboard must be able to run `pithy testers run` and have it say something
+ * sensible. Shipping the mechanism without the words would functionally gate the library behind the
+ * paid tier, which is not on the table.
+ *
+ * **A caller may override the words, and only the words.** The route accepts a subject and a
+ * plain-text body. This capability wraps them in its own layout, branding, footer, and unsubscribe, and
+ * renders the HTML itself.
+ *
+ * **Why the route must never accept HTML.** A control-plane caller supplying nudge content is asking
+ * this Worker to mail arbitrary content to the adopter's own users, signed with the adopter's DKIM. If
+ * that content were unconstrained markup, a compromised dashboard credential would stop being a
+ * disclosure problem and become a phishing platform operating from a domain those users already trust —
+ * the trust being the whole point of DKIM. Bounding the input to text bounds the blast radius: the
+ * worst a compromised caller can send is a lie in prose, which is bad, rather than a credential-harvest
+ * form that renders as the adopter's own product, which is catastrophic.
+ *
+ * The body is split into paragraphs here and handed to the template as an **array of plain strings**,
+ * each rendered through Handlebars' escaping `{{this}}`. So markup in a supplied body cannot become
+ * markup in the sent mail even if every other check were bypassed: the escaping is structural, not a
+ * filter that has to anticipate what to strip.
+ */
+
+/** The shipped default copy for one nudge kind. */
+export interface NudgeCopy {
+  /** The subject line. */
+  readonly subject: string;
+  /** The lead sentence, rendered as the email's heading. */
+  readonly heading: string;
+  /** The body, already split into paragraphs. Each renders escaped. */
+  readonly paragraphs: readonly string[];
+  /** The call-to-action label, when the nudge carries a link. */
+  readonly ctaLabel: string | null;
+}
+
+/**
+ * The shipped defaults, in brand voice: short sentences, deliberate periods, nothing oversold.
+ *
+ * Each is written to be true regardless of what the adopter's app is, because this copy goes out from
+ * their domain and a nudge that overclaims costs them the relationship, not us.
+ */
+const DEFAULTS: Record<NudgeKind, NudgeCopy> = {
+  confirm: {
+    subject: "Can you help test an app?",
+    heading: "Will you be a tester?",
+    paragraphs: [
+      "You have been asked to help test an early build. Answering takes one tap, and it is only a yes — nothing installs yet.",
+      "Once you say yes, the developer adds your address to the test, and you will get a second email with the link to join and install. The test runs for a fixed period and needs everyone who joins to stay joined for the whole of it.",
+    ],
+    ctaLabel: "Yes, count me in",
+  },
+  store: {
+    subject: "You're on the list — here's the link",
+    heading: "Time to join the test",
+    paragraphs: [
+      "You have been added to the test. Use the button below to join and install the app.",
+      "Open it in a browser rather than the store app, and sign in with the same address this email reached you at — the store will not let you join with a different account.",
+      "Stay on the test until the window closes. That is the part that actually counts.",
+    ],
+    ctaLabel: "Join the test",
+  },
+  inactive: {
+    subject: "Still testing?",
+    heading: "We have not seen you in a while",
+    paragraphs: [
+      "You joined the test but have not opened the app recently. If something is broken or in the way, that is worth knowing — it is the reason the test exists.",
+      "If you have uninstalled, no hard feelings. Letting the developer know means they can invite someone else in time.",
+    ],
+    ctaLabel: null,
+  },
+  closing: {
+    subject: "The test window closes soon",
+    heading: "Nearly there",
+    paragraphs: [
+      "The testing period is almost over. Staying enrolled until it closes is what makes it count.",
+      "Nothing is needed from you but that. Thank you for helping.",
+    ],
+    ctaLabel: null,
+  },
+};
+
+/** The shipped default copy for a nudge kind. */
+export function defaultCopy(kind: NudgeKind): NudgeCopy {
+  return DEFAULTS[kind];
+}
+
+/**
+ * Split a supplied plain-text body into paragraphs.
+ *
+ * Blank lines separate paragraphs; single newlines inside one are collapsed to spaces, because a
+ * hard-wrapped paragraph pasted from a terminal should not render as a column of one-line stanzas.
+ * Control characters are stripped: they cannot become markup, but they can smuggle direction overrides
+ * that make a subject line read as something other than what was approved.
+ */
+export function toParagraphs(body: string, maxParagraphs = 20): string[] {
+  return (
+    body
+      // Everything but the newline this function is about to split on. The bidi range is the one worth
+      // naming: a right-to-left override inside a body renders the text after it reversed, which is how
+      // an approved-looking sentence can display as something else entirely.
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point.
+      .replace(/[\u0000-\u0009\u000B-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, "")
+      .split(/\n\s*\n/)
+      .map((paragraph) => paragraph.replace(/\s*\n\s*/g, " ").trim())
+      .filter((paragraph) => paragraph.length > 0)
+      .slice(0, maxParagraphs)
+  );
+}
+
+/**
+ * Flatten a supplied subject to a single safe line.
+ *
+ * **A subject is not an HTML context, so escaping it would be wrong** — `&lt;` in an inbox is a
+ * rendering bug, not a defense, and the email engine precompiles subjects with escaping off for exactly
+ * that reason. The threat in a subject is different and this is what answers it: a carriage return or
+ * newline can terminate the header and let everything after it be read as another header, which is how
+ * a supplied subject becomes an injected `Bcc`. Every control character goes, newlines included, and
+ * the remaining whitespace collapses so a multi-line paste arrives as one line rather than a truncated
+ * one.
+ */
+export function sanitizeSubject(subject: string): string {
+  return (
+    subject
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point.
+      .replace(/[\u0000-\u001F\u007F-\u009F\u200E\u200F\u202A-\u202E\u2066-\u2069]/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+  );
+}
+
+/** Where a nudge's words came from. Recorded on the email job so a send is attributable. */
+export type CopySource = "default" | "supplied";
+
+/** The words one nudge will actually go out with, and their provenance. */
+export interface ResolvedCopy {
+  readonly subject: string;
+  readonly heading: string;
+  readonly paragraphs: readonly string[];
+  readonly ctaLabel: string | null;
+  readonly source: CopySource;
+}
+
+/**
+ * Resolve the copy for a nudge: the caller's words if they supplied any and the deployment allows it,
+ * otherwise the shipped default.
+ *
+ * A caller supplying only a subject keeps the default body, and vice versa. Partial overrides are a
+ * normal thing to want — "same message, our subject line" — and forcing all-or-nothing would push
+ * callers into copying the default body into their request, where it would then never receive an
+ * improvement.
+ */
+export function resolveCopy(kind: NudgeKind, supplied: { subject?: string; body?: string } | undefined): ResolvedCopy {
+  const base = defaultCopy(kind);
+  const subject = supplied?.subject === undefined ? undefined : sanitizeSubject(supplied.subject);
+  const paragraphs = supplied?.body ? toParagraphs(supplied.body) : undefined;
+  const overridden = Boolean(subject) || (paragraphs !== undefined && paragraphs.length > 0);
+
+  return {
+    subject: subject && subject.length > 0 ? subject : base.subject,
+    heading: base.heading,
+    paragraphs: paragraphs && paragraphs.length > 0 ? paragraphs : base.paragraphs,
+    ctaLabel: base.ctaLabel,
+    source: overridden ? "supplied" : "default",
+  };
+}

package/src/nudge/enqueueSeam.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type { EnqueueNudge } from "./send";
+
+/**
+ * The email enqueue seam, loaded from the project's own install.
+ *
+ * A guarded dynamic import: a project can compose testers without email — inviting nobody and simply
+ * tracking a roster it imported — and the pass should still advance state and write its snapshot rather
+ * than fail on a dependency it does not strictly need.
+ *
+ * **Its own module, away from `worker.ts`, because of the clock.** The instant this seam stamps on an
+ * email job is a *liveness* value, not a stamp: `createdAt` is what the email scheduler's grace re-drive
+ * reads to decide a `pending` job never dispatched. The whole of pithy-sh/pithy#328 is that the pass's
+ * other clock — the one deciding the day key — must be journalled and this one must not, and a rule
+ * about a clock that lives in a module no test can import is a rule nothing holds anybody to.
+ */
+
+/** The bindings this seam needs from the worker's env. `TestersWorkerEnv` supplies them. */
+export interface NudgeEnqueueEnv {
+  /** The app database, which holds `pithy_email_jobs` beside the testers tables. */
+  DB: D1Database;
+  /** The sending identity, copied from the email capability's resolved config at provision. */
+  EMAIL_FROM_ADDRESS?: string;
+  EMAIL_FROM_NAME?: string;
+  /** The resolved email theme, as the email worker carries it. */
+  EMAIL_THEME?: string;
+  /**
+   * The project's message catalogs as one JSON var, exactly as the email host worker carries them.
+   *
+   * The **shell** is what this moves — the document's `lang` and `dir`, the footer's opt-out word. A
+   * nudge's own words are the adopter's copy, supplied per message and never in a catalog, so a
+   * translated tester email is only as translated as the copy somebody wrote for it. This capability
+   * holds no per-tester locale to choose with either: a roster is a list of addresses, and inventing a
+   * language for one of them would be worse than the honest English. So the catalogs are threaded and
+   * the tag is not, and the day a member row carries one, this is already the seam it renders through.
+   */
+  [catalogVar: `EMAIL_MESSAGES_${string}`]: unknown;
+  /** The email send Workflow, so an immediate job dispatches now rather than waiting for a cron tick. */
+  EMAIL_SENDER?: { create(options: { params: { jobIds: string[] } }): Promise<unknown> };
+}
+
+/**
+ * Build the enqueue seam, or `undefined` when this deployment cannot send.
+ *
+ * **`clock` is a thunk, and it is read once per enqueued nudge.** That is the liveness half of
+ * pithy-sh/pithy#328 and it is load-bearing, not tidiness. `enqueueEmail` writes the clock it is given
+ * as the job's `createdAt`, and the email scheduler re-drives any `pending` job whose `createdAt` is
+ * older than `graceMs` — on the assumption that its dispatch died. A nudge enqueued under an instant
+ * the pass read minutes or hours ago is therefore born already past that cutoff, so the scheduler
+ * claims and dispatches it while the `EMAIL_SENDER.create` this function just made is still running.
+ * Two send Workflows, one job, and `runSend` short-circuits only a job already `sent`. That is a
+ * double-send, and it is why the pass's journalled instant must never reach this line.
+ */
+export async function buildNudgeEnqueue(
+  env: NudgeEnqueueEnv,
+  clock: () => Date = () => new Date(),
+): Promise<EnqueueNudge | undefined> {
+  // No sending identity means no send. Falling back to a plausible-looking default address would mail
+  // the adopter's testers from a domain their DKIM does not cover, which is worse than sending nothing:
+  // it trains the recipients' providers to treat the real domain as spam.
+  if (!env.EMAIL_FROM_ADDRESS || !env.EMAIL_FROM_NAME) return undefined;
+
+  try {
+    const { enqueueEmail } = await import("@pithy-sh/email/src/send/enqueue");
+    const { emailDatabase } = await import("@pithy-sh/email/src/data/tables");
+    const { defaultTheme, EmailTheme } = await import("@pithy-sh/email/src/templates/theme");
+    const { catalogLayers, catalogsFromEnv } = await import("@pithy-sh/email/src/templates/messages");
+    const theme = env.EMAIL_THEME ? EmailTheme.parse(JSON.parse(env.EMAIL_THEME)) : defaultTheme;
+    // One variable per locale, collected and validated by the same seam the email host uses.
+    const layersFor = catalogLayers(catalogsFromEnv(env as unknown as Record<string, unknown>));
+    const fromAddress = env.EMAIL_FROM_ADDRESS;
+    const fromName = env.EMAIL_FROM_NAME;
+    return async (input) =>
+      enqueueEmail(
+        {
+          db: emailDatabase(env.DB),
+          fromAddress,
+          fromName,
+          theme,
+          layersFor,
+          sender: env.EMAIL_SENDER,
+          // Read here, per nudge — see the note above. Hoisting this out of the closure is the
+          // double-send.
+          now: clock(),
+          newId: () => crypto.randomUUID(),
+        },
+        input,
+      );
+  } catch {
+    return undefined;
+  }
+}