@pithy-sh/testers 0.1.0

package/src/workflows/retryPolicy.ts

@@ -0,0 +1,48 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { WorkflowRetryPolicy } from "@pithy-sh/core/src/workflow/faults";
+
+/**
+ * **What the daily pass retries, and what it refuses to.**
+ *
+ * The pass reads activity, advances state, writes one snapshot per cohort, and enqueues nudges. All of
+ * that is D1: a nudge is a row in `pithy_email_jobs`, and the send Workflow it dispatches afterwards is
+ * the email capability's problem rather than this one's. So there is no `testers/*` code a second
+ * attempt can answer differently, and the record is empty on purpose (pithy-sh/pithy#348).
+ *
+ * **An empty record is a statement, not an omission.** Core answers for D1's transient vocabulary
+ * through `withD1Retry` — busy, timed out, connection lost, storage reset, internal — so a database
+ * under contention is still re-driven, and nothing about that is restated here. What the empty record
+ * adds is that testers retries none of its own codes.
+ *
+ * ## Terminal, and why
+ *
+ * - **`testers/cohort_closed`** — the pass refusing to send from a finished program. That is the
+ *   refusal *working*: a closed cohort keeps its history and sends nothing further, and it does not
+ *   reopen because the step asked again.
+ * - **`testers/cohort_not_found`, `testers/member_not_found`** — a cohort or member deleted between the
+ *   enumeration step and the cohort's own step. Deletion is not undone by a backoff, and this is exactly
+ *   the case one-step-per-cohort exists to contain: the missing cohort loses its snapshot, the other
+ *   cohorts keep theirs.
+ * - **`testers/not_configured`** — no sending identity, no base URL. Config, and identical next time.
+ * - **`testers/roster_full`, `testers/already_on_roster`, `testers/withdrawn`, `testers/invalid_token`,
+ *   `testers/nudge_cooldown`, `testers/copy_not_allowed`** — every one belongs to a control-plane
+ *   request or a tester's own click. The pass raises none of them.
+ * - **`validation/invalid_input`** — a `TestersDailyParams` an operator dispatched by hand.
+ *
+ * **The cron is the outer retry, and the pass is contained per cohort.** A cohort whose step fails loses
+ * its own day rather than everyone's, and the day after that runs again. Five platform attempts against
+ * a closed cohort would spend the pass's budget re-asking a question whose answer is a person's or an
+ * adopter's decision.
+ *
+ * **What this cannot say.** A `EMAIL_SENDER.create` that fails throws whatever the Workflows binding
+ * threw — not a `PithyError`, so `unclassified`, so terminal. The job row is already written and
+ * `pending`, and the email scheduler's grace re-drive claims a `pending` job whose dispatch died, so the
+ * nudge is not lost; it is late. That is the correct outcome, but it is a default rather than a decision
+ * and no policy record can turn it into one.
+ */
+export const testersWorkflowRetry: WorkflowRetryPolicy = {
+  capability: "testers",
+  retryable: {},
+};

package/src/workflows/specs.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry, WorkflowSpecMap } from "@pithy-sh/core/src/workflow/spec";
+import { z } from "zod";
+
+/** This capability's name, and the first segment of every workflow dispatch key. */
+export const TESTERS_CAPABILITY = "testers";
+
+/**
+ * The daily pass's parameters.
+ *
+ * **Every field is optional, which is a requirement rather than a convenience.** A cron supplies no
+ * input, and `createEntrypoint` dispatches a scheduled job with `{}` — so a schema demanding a field
+ * could never run on its own schedule. The fields exist for the on-demand case: running one cohort in
+ * staging, or checking what a pass would do before letting it mail twelve people.
+ */
+export const TestersDailyParams = z
+  .object({
+    cohortId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("Run the pass for one cohort only. Omit for every open cohort, which is what the cron does."),
+    skipNudges: z
+      .boolean()
+      .optional()
+      .describe(
+        "Advance state and write the snapshot, but send nothing. The safe way to exercise the pass in staging against real testers.",
+      ),
+  })
+  .describe("What one daily pass should do. Every field optional, because a cron passes none of them.");
+export type TestersDailyParams = z.infer<typeof TestersDailyParams>;
+
+/**
+ * The one durable job this capability owns.
+ *
+ * **Daily at 05:00 UTC**, offset from storage's 03:00 sweep, the secrets rotation at 03:00, and
+ * payments' 04:00 reconciliation, so four hosts in one account do not contend for the same minute.
+ * Daily is the right cadence because the thing being measured is a day counter: an hourly pass would
+ * write the same row twenty-four times and change the answer on none of them.
+ *
+ * It is a cron **and** a dispatch target. A pass nobody can run on demand cannot be tested in staging,
+ * which is precisely when a developer wants to know what it will send.
+ *
+ * `optional: true` because the binding exists only once `pithy testers provision` has deployed the
+ * host, and a project that has not provisioned it must still be able to invite testers, accept
+ * confirmations, and read its cohorts.
+ */
+export const testersWorkflows = {
+  daily: {
+    binding: "TESTERS_DAILY",
+    className: "TestersDailyWorkflow",
+    params: TestersDailyParams,
+    schedule: "0 5 * * *",
+    optional: true,
+  },
+} as const satisfies WorkflowSpecMap;
+
+/**
+ * The jobs as a dispatch registry, keyed `testers/<job>`.
+ *
+ * Built here rather than through `composeWorkflows` because the host worker dispatches its own job
+ * before any project-wide registry exists — and the key format comes from core's `workflowKey` either
+ * way, so the two cannot drift.
+ */
+export const testersWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
+  Object.entries(testersWorkflows).map(([job, spec]) => {
+    const key = workflowKey(TESTERS_CAPABILITY, job);
+    return [key, { key, capability: TESTERS_CAPABILITY, job, spec }];
+  }),
+);

package/src/workflows/worker.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+import { NonRetryableError } from "cloudflare:workflows";
+import type { D1Database } from "@cloudflare/workers-types";
+import { bindWorkflowContext, createWorkerLogger } from "@pithy-sh/core/src/logger/worker";
+import { triggerWorkflow } from "@pithy-sh/core/src/workflow/dispatch";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { confirmUrl, optInUrl, optOutUrl, TestersConfig } from "../config/config";
+import type { NudgeKind } from "../data/enums";
+import type { TestersMember } from "../data/member";
+import { testersDatabase } from "../data/tables";
+import { buildNudgeEnqueue, type NudgeEnqueueEnv } from "../nudge/enqueueSeam";
+import type { EnqueueNudge } from "../nudge/send";
+import type { CohortPassResult } from "./daily";
+import { runDurableDailyPass } from "./pass";
+import { testersWorkflowRetry } from "./retryPolicy";
+import { TESTERS_CAPABILITY, TestersDailyParams, testersWorkflowRegistry } from "./specs";
+
+/**
+ * The prebuilt worker hosting the daily pass.
+ *
+ * **Why its own worker rather than the app worker's `scheduled()`.** The pass can mail every tester on
+ * every roster. Keeping it out of the request-serving deployment means it cannot compete with a
+ * tester's confirmation click for CPU, and — more to the point — the app worker never needs a binding
+ * that can send mail to an entire roster on a timer. It is a Workflow rather than a plain scheduled
+ * handler because a Worker invocation is wall-clock bounded while a Workflow step is not: several
+ * cohorts of a hundred testers each is a job you want checkpointed rather than restarted.
+ *
+ * This is the only module in the package that imports `cloudflare:workers`, which is why the
+ * schema-description meta-test excludes it — the import is unresolvable outside the Workers runtime.
+ */
+
+/**
+ * The bindings and vars this worker's env carries, filled by `pithy testers provision`.
+ *
+ * The sending identity and the send binding are carried as vars rather than guessed, because this
+ * worker is standalone: it is not assembled by `createBackend`, so the email capability's `compose`
+ * hook never runs here and there is no bound `enqueue` seam to borrow. A default would be worse than an
+ * absent value — mail from the wrong domain fails DKIM and lands the adopter's testers in spam, which is
+ * exactly the outcome this capability exists to avoid. They are declared on {@link NudgeEnqueueEnv},
+ * beside the seam that reads them.
+ */
+export interface TestersWorkerEnv extends NudgeEnqueueEnv {
+  DB: D1Database;
+  TESTERS_CONFIG?: string;
+  ENVIRONMENT?: string;
+  /** The global email-suppression database, for reconciling which addresses have bounced. */
+  EMAIL_SUPPRESSIONS?: D1Database;
+}
+
+/** The daily pass over every open cohort. */
+export class TestersDailyWorkflow extends WorkflowEntrypoint<TestersWorkerEnv, TestersDailyParams> {
+  override async run(event: WorkflowEvent<TestersDailyParams>, step: WorkflowStep): Promise<CohortPassResult[]> {
+    // Parse rather than trust: an instance can be started by the cron, by `c.var.workflows.trigger`, or
+    // by an operator through the dashboard, and only the first two have already been validated.
+    const params = TestersDailyParams.parse(event.payload ?? {});
+    const config = TestersConfig.parse(this.env.TESTERS_CONFIG ? JSON.parse(this.env.TESTERS_CONFIG) : {});
+
+    // A run has no request, so there is no `c.var.log` to inherit: the Workflow builds its own and binds
+    // the instance onto it. That id is what the dashboard and `wrangler workflows` key on, so binding it
+    // once here is what lets an operator read a whole pass — the tally and every failed cohort — as one
+    // correlated set. It is handed to the pass too, so a suppression list it could not read says so
+    // against the same instance.
+    const log = bindWorkflowContext(createWorkerLogger({ name: `${TESTERS_CAPABILITY}:daily` }), {
+      workflow: event.workflowName,
+      instance: event.instanceId,
+      env: this.env.ENVIRONMENT ?? "unknown",
+    });
+
+    // Built with the default clock, which the seam reads **per nudge**. This is the pass's other clock
+    // and it is the opposite of the journalled one: see `enqueueSeam.ts`.
+    const enqueue: EnqueueNudge | undefined = params.skipNudges ? undefined : await buildNudgeEnqueue(this.env);
+    const linkForKind = params.skipNudges ? undefined : linkFor(config);
+
+    return runDurableDailyPass(
+      {
+        db: testersDatabase(this.env.DB),
+        d1: this.env.DB,
+        config,
+        newId: () => crypto.randomUUID(),
+        log,
+        enqueue,
+        linkFor: linkForKind,
+        optOutLinkFor: (member: TestersMember) => optOutUrl(config, member.optInToken),
+        suppressionD1: this.env.EMAIL_SUPPRESSIONS,
+      },
+      // Under `testersWorkflowRetry`, whose record is empty and says so: the pass is D1, core answers
+      // for D1, and a closed cohort or a deleted member is a decision rather than an outage. Contained
+      // per cohort already, so a terminal fault loses one cohort's day, not everyone's.
+      classifiedSteps(step, testersWorkflowRetry, NonRetryableError),
+      params,
+    );
+  }
+}
+
+/**
+ * Build the link a nudge carries.
+ *
+ * No secret, no minting, no failure mode: the token lives on the member row, so this is string
+ * concatenation. That is the whole reason the token stopped being a signature.
+ */
+function linkFor(config: TestersConfig): (kind: NudgeKind, member: TestersMember) => string | undefined {
+  return (kind, member) => {
+    if (kind === "confirm") return confirmUrl(config, member.optInToken);
+    if (kind === "store") return optInUrl(config, member.optInToken);
+    return undefined;
+  };
+}
+
+export default {
+  /**
+   * Cron entry: start one pass per fire, with empty parameters — the defaults are the scheduled
+   * behavior.
+   *
+   * Through the same dispatcher an on-demand pass uses, rather than `env.TESTERS_DAILY.create()`: the
+   * parameters are validated against the job's own schema before the binding is touched, and a host
+   * deployed with the binding absent or renamed logs a skip instead of throwing inside a cron nobody is
+   * watching. A daily job that fires, does nothing, and says nothing is the one failure mode this pass
+   * cannot afford — because silence is also what success looks like.
+   */
+  async scheduled(_controller: unknown, env: TestersWorkerEnv): Promise<void> {
+    await triggerWorkflow(
+      env as unknown as Record<string, unknown>,
+      testersWorkflowRegistry,
+      "testers/daily",
+      {},
+      createWorkerLogger(),
+    );
+  },
+};

package/src/workflows/wrangler.jsonc

@@ -0,0 +1,66 @@
+{
+  // The prebuilt testers daily-pass worker. Like the email, media, storage and payments workers, this is
+  // a TEMPLATE rather than a wrangler env-stanza file: staging and prod are genuinely separate
+  // workers. `pithy testers provision` resolves it into one complete config per environment — filling
+  // the `<...>` placeholders and deriving the `workflows` array and the cron from the capability's
+  // specs — and deploys each with `wrangler deploy --config <resolved>`. The adopter authors none of it.
+  // Resolved per project and env → <project>-staging-testers / <project>-prod-testers. Worker
+  // script names are account-scoped, so the project segment is what stops a second Pithy project's
+  // deploy overwriting this one's running worker instead of colliding with it.
+  "name": "pithy-testers",
+  "main": "./worker.ts",
+  // The compatibility date every Worker in this repository runs on. Stated once in the repository
+  // root's `compatibility.ts` and copied here because JSONC cannot import it —
+  // `cli/src/ci/compatibilityDates.test.ts` fails on any Worker older than it.
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // No public URL. Every testers route lives in the app worker; this one is reached only by its cron and
+  // by Workflow dispatch. It can mail every tester on every roster, so it stays off workers.dev.
+  "workers_dev": false,
+
+  // Two databases and no more. The app database holds the pithy_testers_* tables, the pithy_auth_*
+  // tables the activity reader joins against, and the pithy_email_jobs rows a nudge becomes. The
+  // suppression database is shared across the project's environments rather than per environment — an
+  // unsubscribe in prod must stop staging too — and the daily pass reads it to reconcile which
+  // addresses have bounced. Its name resolves to <project>-global-email-suppressions at provision.
+  //
+  // No SECRETS binding and no master key: the confirmation token is a random value on the tester's own
+  // row rather than a signature, so this worker reads no secret at all. That is the whole reason
+  // `pithy testers invite` works against any environment.
+  "d1_databases": [
+    { "binding": "DB", "database_name": "pithy-app", "database_id": "<filled-at-provision>" },
+    {
+      "binding": "EMAIL_SUPPRESSIONS",
+      "database_name": "pithy-email-suppressions",
+      "database_id": "<filled-at-provision>"
+    }
+  ],
+
+  // The one Workflow this worker hosts. Rewritten at provision from `workflows/specs.ts`, so the binding,
+  // the class name, and the per-environment deployed name come from the spec rather than from this block —
+  // it is here so the template reads as a complete config.
+  "workflows": [{ "binding": "TESTERS_DAILY", "name": "pithy-testers-daily", "class_name": "TestersDailyWorkflow" }],
+
+  // The daily pass, at 05:00 UTC. Also rewritten at provision from the spec's `schedule`. Offset from
+  // storage's 03:00 sweep, the secrets rotation at 03:00, and payments' 04:00 reconciliation, so four
+  // hosts in one account do not contend for the same minute.
+  "triggers": { "crons": ["0 5 * * *"] },
+
+  "vars": {
+    // The resolved TestersConfig as one JSON blob, filled at provision from the app's testers() config.
+    // The pass reads the cooldown, the survival priors, the health weights, and the base URL from it.
+    "TESTERS_CONFIG": "<filled-at-provision>",
+
+    // The sending identity, copied from the email capability's resolved config. Carried as vars because
+    // this worker is standalone — it is not assembled by `createBackend`, so email's `compose` hook
+    // never runs here and there is no bound `enqueue` seam to borrow. Absent means the pass advances
+    // state and records the day but sends nothing, which is better than mailing an adopter's testers
+    // from a domain their DKIM does not cover.
+    "EMAIL_FROM_ADDRESS": "<filled-at-provision>",
+    "EMAIL_FROM_NAME": "<filled-at-provision>",
+    "EMAIL_THEME": "<filled-at-provision>",
+
+    "ENVIRONMENT": "<filled-at-provision>"
+  }
+}