@pithy-sh/email 0.1.0

package/src/workflows/params.ts

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * What each of email's two durable jobs is started with.
+ *
+ * Declared here rather than inline on the capability because **three places now need the same
+ * object**: the capability's `workflows` map (which is what the app worker dispatches through), the
+ * host's mirrored registry in `provision/resolveEmailConfig.ts` (which derives the deployed Workflow
+ * names), and the host's dispatch route, which validates an incoming loopback payload against the
+ * declaring spec's own schema before it starts anything (pithy-sh/pithy#410).
+ *
+ * That last one is why the mirror could no longer carry `z.unknown()`. A params schema that accepts
+ * everything turns a malformed dispatch into a durable instance that fails somewhere inside its first
+ * step, which is exactly the class of failure the request contract exists to name at the door.
+ */
+
+/** The batch of queued rows one send Workflow instance is responsible for. */
+export const EmailSendParams = z
+  .object({
+    jobIds: z
+      .array(z.string().min(1).describe("A queued `pithy_email_jobs` row id."))
+      .min(1)
+      .describe("The batch of queued job ids this instance sends — one durable step each."),
+  })
+  .describe("Parameters for one durable send batch.");
+export type EmailSendParams = z.infer<typeof EmailSendParams>;
+
+/** The scheduler's parameters: none. It finds its own work. */
+export const EmailScheduleParams = z
+  .object({})
+  .describe("The scheduler takes no parameters — it finds its own due jobs.");
+export type EmailScheduleParams = z.infer<typeof EmailScheduleParams>;

package/src/workflows/scheduler.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { chunkByBoundParameters } from "@pithy-sh/core/src/data/boundParameters";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { EmailDatabase } from "../data/tables";
+
+/**
+ * The every-minute scheduler. It finds due rows — `scheduled`/`timezone` jobs whose `sendAt` has
+ * arrived, plus the safety net of `pending` and `undispatched` immediate jobs that never dispatched and
+ * `sending` jobs left stale by a dead dispatch — claims them (status → `sending`, so the next tick won't
+ * repick them), and fans them out into sender batches. **The fan-out scales with volume:** the more rows are due, the
+ * more batches are dispatched, each its own durable send Workflow. Cron is cheap; this runs every
+ * minute and does nothing when nothing is due.
+ *
+ * Jobs are claimed before dispatch, so a dispatch failure strands a row in `sending` rather than
+ * double-sending; the `sending` re-drive recovers it on a later tick, and `runSend`'s idempotency makes
+ * any recovery a no-op for a job that did go out.
+ *
+ * **The claim is the batch.** Every job claimed in one dispatch carries that batch's id, which is the id
+ * of the send Workflow instance started for it, so the tick that finds those rows stale can ask the
+ * runtime whether the batch is still alive instead of guessing from a timestamp. That is the whole of
+ * the re-drive decision (pithy-sh/pithy#342), and it costs the claim one column and the tick one question
+ * per batch.
+ */
+
+/** Inputs the scheduler needs. `dispatch` creates one send Workflow per batch. */
+export interface SchedulerDeps {
+  db: EmailDatabase;
+  now: Date;
+  /** How stale (ms) a `pending`/`undispatched` immediate job must be before the safety net re-drives it. */
+  graceMs: number;
+  /**
+   * How stale (ms) a job must be before this tick will *consider* re-driving it.
+   *
+   * **It is a filter, not the verdict.** A row's timestamp cannot say whether the batch holding it is
+   * alive: a batch is claimed whole and walked one job at a time, so a job it has not reached carries the
+   * claim instant however busy the batch is, and a step waiting out its retry backoff writes nothing at
+   * all while being entirely alive. {@link SchedulerDeps.batchIsAlive} settles both; this only decides
+   * what is old enough to ask about (pithy-sh/pithy#342).
+   *
+   * So it is not a knob for outrunning a long queue. Widening it to cover one would be a race with a
+   * slower horse, and the queue gets longer.
+   */
+  stuckMs: number;
+  /**
+   * Jobs per dispatched batch — one send Workflow each. From `SCHEDULER_BATCH_SIZE`.
+   *
+   * **A fan-out knob, and nothing else.** It has no ceiling: the claim statement sizes itself against
+   * D1's bound-parameter cap independently, so raising this changes how many Workflows a tick starts and
+   * cannot make a statement too wide. It used to be both, and 100 was enough to fail every tick (#250).
+   */
+  batchSize: number;
+  /** The most jobs to claim in one tick. */
+  maxJobs: number;
+  /**
+   * Mint the id of a batch about to be dispatched. It **is** the send Workflow's instance id, which is
+   * what lets {@link SchedulerDeps.batchIsAlive} ask the runtime about it later.
+   */
+  newBatchId: () => string;
+  /**
+   * Is the send Workflow instance holding this batch still alive? (pithy-sh/pithy#342)
+   *
+   * The question a row cannot answer. A Workflow that exists and is scheduled to retry is alive, and its
+   * rows are as untouched as a dead dispatch's; a batch three quarters of the way down a long queue is
+   * alive, and the quarter it has not reached is as untouched again. Both used to read as stranded, and
+   * a re-drive of either is a second send Workflow over a job the first will reach — a double-send.
+   *
+   * **It may only ever veto a re-drive, never cause one.** A stale row with no batch, or one whose batch
+   * this cannot vouch for, is re-driven exactly as it was before this existed. That is what keeps the
+   * safety net intact and makes the new question incapable of sending an extra email: the worst an
+   * unavailable answer can do is decline to save one.
+   */
+  batchIsAlive: (batchId: string) => Promise<boolean>;
+  /** Create a send Workflow for a batch of job ids, under the batch's id as the instance id. */
+  dispatch: (batchId: string, jobIds: string[]) => Promise<void>;
+}
+
+/** What one scheduler tick did. */
+export interface SchedulerResult {
+  /** How many due jobs were claimed. */
+  due: number;
+  /** How many batches were dispatched (scales with volume). */
+  batches: number;
+  /** How many stale-looking jobs were left alone because the batch holding them is still alive. */
+  held: number;
+}
+
+/**
+ * How many parameters the claim statement binds besides the job ids: `status`, `updatedAt`, `batchId`.
+ *
+ * Named here so that adding a column to the `set` is a one-number edit beside it, rather than a silent
+ * re-break of a limit nobody re-derived.
+ */
+const CLAIM_FIXED_PARAMETERS = 3;
+
+/**
+ * Refuse a batch size that is not a count at all — checked before the tick does any work.
+ *
+ * `Number(env.SCHEDULER_BATCH_SIZE)` yields `NaN` for a typo, and `NaN` used to produce exactly one
+ * empty batch: no job claimed, no job sent, no error, every minute. There is no safe number to clamp a
+ * typo to, so it is named and refused.
+ *
+ * What is *not* refused is a large one. It carries no platform limit any more — see
+ * {@link dispatchBatches}.
+ */
+function assertBatchSize(batchSize: number): void {
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    throw new ValidationError({
+      message: "The email scheduler is misconfigured.",
+      action: "Set SCHEDULER_BATCH_SIZE to a whole number of one or more, or unset it for the default of 50.",
+      detail: `SCHEDULER_BATCH_SIZE resolved to ${batchSize}; it must be a positive integer.`,
+    });
+  }
+}
+
+/**
+ * Split the due jobs into the batches this tick will dispatch — the **fan-out** split, not the
+ * parameter one.
+ *
+ * The two used to be the same list, which is how `SCHEDULER_BATCH_SIZE` came to decide the width of a
+ * D1 statement. They are separated now: this decides how many send Workflows a tick starts, and
+ * {@link chunkByBoundParameters} decides how wide the claim that precedes each one may be. So the
+ * operator's number carries no platform limit, and the platform limit needs no operator.
+ */
+function dispatchBatches(ids: string[], batchSize: number): string[][] {
+  const out: string[][] = [];
+  for (let start = 0; start < ids.length; start += batchSize) out.push(ids.slice(start, start + batchSize));
+  return out;
+}
+
+/**
+ * Drop the candidates a live batch still holds, and return the rest (pithy-sh/pithy#342).
+ *
+ * A candidate is a row the timestamps say *might* be stranded. Deciding it actually is takes the batch,
+ * so every row naming one is settled by {@link SchedulerDeps.batchIsAlive} — asked **once per batch**,
+ * not once per row, because fifty rows of a stalled batch are one question about one Workflow.
+ *
+ * A row naming no batch is stranded by definition: nothing claimed it, or whatever did died before it
+ * could say so. That is the safety net, and it is deliberately untouched here.
+ */
+async function strandedIds(
+  deps: SchedulerDeps,
+  rows: readonly { id: string; batchId?: string | null }[],
+): Promise<string[]> {
+  const answered = new Map<string, boolean>();
+  const stranded: string[] = [];
+  for (const row of rows) {
+    const batchId = row.batchId;
+    if (batchId) {
+      let alive = answered.get(batchId);
+      if (alive === undefined) {
+        alive = await deps.batchIsAlive(batchId);
+        answered.set(batchId, alive);
+      }
+      if (alive) continue;
+    }
+    stranded.push(row.id);
+  }
+  return stranded;
+}
+
+/** Run one scheduler tick: find due rows, claim them, fan out batches. */
+export async function runScheduler(deps: SchedulerDeps): Promise<SchedulerResult> {
+  // Before the query, so a misconfigured worker says so on its first tick rather than on its first
+  // busy one. An idle cron that quietly accepts a broken batch size is the shape of the bug, not a
+  // reason to postpone the complaint.
+  assertBatchSize(deps.batchSize);
+  const nowMs = deps.now.getTime();
+  const graceCutoff = nowMs - deps.graceMs;
+  const stuckCutoff = nowMs - deps.stuckMs;
+
+  const rows = await deps.db
+    .selectFrom("pithyEmailJobs")
+    .select(["id", "batchId"])
+    .where((eb) =>
+      eb.or([
+        eb.and([eb("status", "=", "scheduled"), eb("sendAt", "<=", nowMs)]),
+        // `undispatched` beside `pending`, and it is the whole recovery path for one
+        // (pithy-sh/pithy#410). A row born `undispatched` was enqueued by a composition that binds no
+        // send Workflow — deployed before `pithy <capability> provision`, or a plain `wrangler dev` —
+        // and the tick reading this query is running on the host that composition was missing. So the
+        // first tick after the host exists is what drains that backlog; without this line the row is a
+        // dead end, because `retryJob` takes only `failed` and no command moves it.
+        eb.and([eb("status", "in", ["pending", "undispatched"]), eb("createdAt", "<=", graceCutoff)]),
+        eb.and([eb("status", "=", "sending"), eb("updatedAt", "<=", stuckCutoff)]),
+      ]),
+    )
+    .orderBy("sendAt", "asc")
+    .limit(deps.maxJobs)
+    .execute();
+
+  if (rows.length === 0) return { due: 0, batches: 0, held: 0 };
+
+  const ids = await strandedIds(deps, rows);
+  const held = rows.length - ids.length;
+  if (ids.length === 0) return { due: 0, batches: 0, held };
+
+  const batches = dispatchBatches(ids, deps.batchSize);
+  let dispatched = 0;
+  for (const batch of batches) {
+    // The batch's id, minted before the claim so the rows can carry it: it is the send Workflow's
+    // instance id, and a row that names it is a row the next tick can ask the runtime about.
+    const batchId = deps.newBatchId();
+    // Claim this batch first so a re-run never double-dispatches it, then start its send Workflow. The
+    // claim is chunked against D1's cap, so a batch of any size is claimed in full before it dispatches
+    // — a batch wider than one statement takes several, and the batch is still one unit of work.
+    for (const claim of chunkByBoundParameters(batch, CLAIM_FIXED_PARAMETERS)) {
+      await deps.db
+        .updateTable("pithyEmailJobs")
+        .set({ status: "sending", updatedAt: nowMs, batchId })
+        .where("id", "in", claim)
+        .execute();
+    }
+    await deps.dispatch(batchId, batch);
+    dispatched += 1;
+  }
+
+  return { due: ids.length, batches: dispatched, held };
+}

package/src/workflows/sendBatch.ts

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { runSend, type SendDeps, type SendOutcome } from "../send/runSend";
+
+/**
+ * The send batch — the body `EmailSendWorkflow.run` hands its step runner to.
+ *
+ * **Why it is here and not in the Workflow class.** `worker.ts` imports `cloudflare:workers`, which
+ * resolves in workerd and nowhere else, so anything inside it can only be exercised by deploying it.
+ * Every property worth proving about this body is a property of a *resume* — a Workflow does not resume
+ * inside the step it died in, it re-executes this function from the top and serves every completed step
+ * from the journal — and the only way to know a resume behaves is to drive one.
+ *
+ * **One step per job.** Each is independently retried and backed off by the Workflow runtime, and a step
+ * whose retries are spent is contained here, so a single bad recipient never blocks the rest of the
+ * batch. That sentence has been in this docblock since the file was written and the code did not do it
+ * until #380: the throw came out of the loop and took every job behind it, on this attempt and on every
+ * replay of the body.
+ *
+ * **The batch is the unit of liveness, and it says so by existing.** The scheduler claims a whole batch
+ * up front, stamps every row with the batch's id — which is this Workflow instance's id — and dispatches
+ * one instance for it. So a job this body has not reached is queued, not stranded, and the scheduler
+ * establishes that by asking the runtime whether the instance is still running.
+ *
+ * That is why nothing here writes to a job it is not sending. The previous answer had each step renew the
+ * claim on every job behind it (pithy-sh/pithy#340), which is correct and costs N(N-1)/2 row updates for
+ * a batch of N — 1,225 at the shipped batch size of 50, on a setting with no ceiling — and still could
+ * not speak for a step waiting out its retry backoff, because a body that is not running renews nothing
+ * (pithy-sh/pithy#342). One question to the runtime answers both, and writes nothing.
+ */
+
+/** The durable step runner, structurally. Injected, so a test can drive an interrupt and a resume. */
+export interface SendBatchStep {
+  /** Run a named step, or return its journaled result if this instance already completed it. */
+  do<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * What a batch needs: everything one send needs, minus the pass instant it journals for itself.
+ *
+ * `heartbeatAt` is the clock, and it stays a thunk all the way down — `runSend` reads it afresh on every
+ * patch. The pass instant is *one journaled read of the same clock*, which is the whole design in a
+ * sentence: one source, two lifetimes, and neither of them able to answer for the other.
+ */
+export type SendBatchDeps = Omit<SendDeps, "passStartedAt">;
+
+/**
+ * One job's place in the batch — **two states, and the outcome lives behind the one that has it**
+ * (#380).
+ *
+ * A step exhausts its retries and throws, and the docblock above promises that never blocks the rest of
+ * the batch. It did not: the throw propagated out of the loop and every job behind it went unsent, on
+ * this attempt and on every retry of the body, because a re-execution replays the journal and reaches
+ * the same failing step again. A batch of fifty lost forty-seven messages to one bad recipient.
+ *
+ * The two states share no field, so a caller cannot reach an outcome without narrowing, and a job the
+ * batch could not finish cannot be read as one that was skipped for a reason `runSend` names. What
+ * happens to that job next is the scheduler's: its row is still `sending` or `failed`, and the
+ * `stuckMs` re-drive is what picks it up.
+ */
+export type BatchJobResult =
+  | {
+      /** The send ran to a conclusion — sent, suppressed, canceled or terminally failed. */
+      state: "attempted";
+      /** The job this is about. */
+      jobId: string;
+      /** What the send concluded. Present here alone. */
+      outcome: SendOutcome;
+    }
+  | {
+      /**
+       * The step did not finish: it threw, and its retries within this instance are spent. Nothing is
+       * claimed about the job beyond that — it may have been rendered, it may have been sent and the
+       * write lost.
+       */
+      state: "unfinished";
+      /** The job this is about — the only fact this state carries. */
+      jobId: string;
+    };
+
+/**
+ * What one batch did, one entry per job in dispatch order.
+ *
+ * Returned rather than logged because this capability has no logger seam and a Workflow's return value
+ * *is* its instance output — so the record lands where an operator already looks when a batch is in
+ * question, next to the step journal that shows which step failed.
+ */
+export interface BatchSendReport {
+  /** One entry per job id the batch was dispatched with, in that order. */
+  jobs: BatchJobResult[];
+}
+
+/** Send one batch of jobs, one durable step each. */
+export async function runSendBatch(
+  deps: SendBatchDeps,
+  step: SendBatchStep,
+  jobIds: readonly string[],
+): Promise<BatchSendReport> {
+  /**
+   * The pass instant, journaled (pithy-sh/pithy#327).
+   *
+   * One read of `heartbeatAt`, taken inside a step so a resume reads back the instant the batch began
+   * rather than the instant it came back. It dates the work — `sentAt`, the redaction stamp, the events,
+   * and every tracked link's expiry.
+   *
+   * **What is deliberately not journaled is the clock itself.** `deps.heartbeatAt` goes through to
+   * `runSend` as a thunk, because `updatedAt` is what decides a `sending` job is old enough to ask about
+   * at all, and a frozen one puts a job the batch is mid-flight on in front of that question every tick.
+   * The batch's own liveness answers it correctly either way; a clock that lies is still a clock that
+   * lies, and `sentAt` is not the only thing reading this.
+   *
+   * Epoch milliseconds rather than a `Date`, because a journal round-trips JSON: a `Date` would come back
+   * a string on the resume and an object on the first pass.
+   */
+  const passStartedAtMs: number = await step.do("pass-instant", async () => deps.heartbeatAt().getTime());
+  const sendDeps: SendDeps = { ...deps, passStartedAt: new Date(passStartedAtMs) };
+  const jobs: BatchJobResult[] = [];
+  for (const jobId of jobIds) {
+    // Contained per job, which is what the docblock above has always claimed (#380). A step that has
+    // spent its retries throws, and the throw used to end the batch — so one recipient whose template
+    // will not render, or whose row was deleted mid-flight, cost every job behind it its send.
+    //
+    // `try`/`catch` rather than `.catch()`: `step.do` is handed a function, and a runner that throws
+    // before it returns a promise is not a rejected promise (#371).
+    //
+    // **The guard takes no binding.** What a send throws carries a recipient's address, a provider's
+    // response, and sometimes the rendered link itself — none of which may travel into a value the
+    // Workflow instance publishes as its output. The job id is the actionable fact and it is already
+    // here. The failure itself stays exactly where it is visible and belongs: the failed step in the
+    // instance's own journal.
+    //
+    // **The step runner is not one of the contributors, and `began` is what tells them apart.** A send
+    // that ran and failed is this job's failure and is contained. A runner that will not start the step
+    // at all is the durable mechanism itself refusing — an instance being torn down — and there is no
+    // batch left to carry on: every job behind would fail identically, and a body that keeps calling a
+    // runner which has refused is a body that has not noticed it is being killed. So that one is
+    // rethrown, exactly as `readProjectLedger` still throws when the databases cannot be enumerated.
+    let began = false;
+    try {
+      const outcome = await step.do(`send-${jobId}`, async () => {
+        began = true;
+        return await runSend(sendDeps, jobId);
+      });
+      jobs.push({ state: "attempted", jobId, outcome });
+    } catch (interrupted) {
+      // The binding exists only to rethrow the same object, unchanged. Nothing derived from it reaches
+      // the report — that is what `unfinished` carrying only a job id means.
+      if (!began) throw interrupted;
+      jobs.push({ state: "unfinished", jobId });
+    }
+  }
+  return { jobs };
+}

package/src/workflows/worker.ts

@@ -0,0 +1,203 @@
+// 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, ExecutionContext } from "@cloudflare/workers-types";
+import { classifiedSteps } from "@pithy-sh/core/src/workflow/faults";
+import { requireHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
+import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
+import { configureSharedSecrets } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { emailSigningRegistry, resolveSigningKeys } from "../crypto/signingKey";
+import { emailDatabase, emailSuppressionDatabase } from "../data/tables";
+import { mintBatchId } from "../send/batchIdentity";
+import type { SendWorkflowBinding } from "../send/enqueue";
+import { emailWorkflowRetry } from "../send/retryPolicy";
+import type { EmailSender } from "../send/sender";
+import { catalogLayers, catalogsFromEnv } from "../templates/messages";
+import { createEmailHostApp } from "./hostApp";
+import { type EmailHostEnv, emailHostEnv } from "./hostEnv";
+import { isLiveInstanceStatus } from "./instanceLiveness";
+import type { SendWorkflowInstances } from "./instances";
+import { runScheduler, type SchedulerDeps } from "./scheduler";
+import { type BatchSendReport, runSendBatch, type SendBatchDeps } from "./sendBatch";
+
+/**
+ * The prebuilt email worker. `pithy add email` deploys one per environment (`pithy-email-staging`,
+ * `pithy-email-prod`); the user authors no code for it. It hosts:
+ *
+ *   - `EmailSendWorkflow` — sends a batch of jobs durably (dispatch target for immediate sends and
+ *     the scheduler's fan-out).
+ *   - `EmailSchedulerWorkflow` — finds due jobs and fans them out into send batches.
+ *   - `scheduled()` — the every-minute cron that fires the scheduler Workflow.
+ *   - `fetch()` — the loopback dispatch door, served only in `dev` (see {@link createEmailHostApp}).
+ *
+ * The bodies (`runSendBatch`, `runScheduler`, `runSend`) are tested against Miniflare; these classes are
+ * the thin durable shells. This module imports `cloudflare:workers`, so it runs only in the Workers
+ * runtime (excluded from the node meta-test).
+ *
+ * **Every entry validates the env first** (pithy-sh/pithy#410). Fourteen settings arrived here from a
+ * provisioning run and none of them was checked: a missing `BASE_URL` became a magic link to
+ * `undefined/…`, an unparseable `EMAIL_THEME` threw inside a render step, and a `SCHEDULER_BATCH_SIZE`
+ * of `"fifty"` became `NaN` and the scheduler claimed nothing, forever, in silence. Now
+ * {@link emailHostEnv} is parsed before anything reads a value, the coercions and defaults live in
+ * that one schema rather than at each reader, and a host that cannot work says so in one block and
+ * refuses.
+ */
+
+/**
+ * The email worker's env as the runtime hands it over — bindings as objects, every var as a string.
+ *
+ * The *shape the host runs on* is {@link EmailHostEnv}, which is this parsed: numbers as numbers, the
+ * theme as a validated `EmailTheme`, `SCHEDULER_ENABLED` as a boolean. This type stays because it is
+ * what a `WorkflowEntrypoint` is generic over and what the platform actually binds.
+ */
+export interface EmailWorkerEnv extends SecretsStoreEnv {
+  /** The app database the per-environment jobs/events tables live in. */
+  DB: D1Database;
+  /** The shared, durable suppression database. */
+  EMAIL_SUPPRESSIONS: D1Database;
+  /** The Cloudflare Email Service send binding. */
+  EMAIL: EmailSender;
+  /** The send Workflow (self) — the scheduler creates batches against it, and asks after them. */
+  EMAIL_SENDER: SendWorkflowBinding & SendWorkflowInstances;
+  /** The scheduler Workflow (self) — fired by the cron. */
+  EMAIL_SCHEDULER: { create(): Promise<unknown> };
+  /** The resolved brand theme as a JSON string (the full `EmailTheme`), set at provision from the app config. */
+  EMAIL_THEME?: string;
+  /**
+   * The project's catalogs arrive as one variable per locale — `EMAIL_MESSAGES_ES` and friends — read
+   * through `catalogsFromEnv`. Not declared here, because the names are the project's locales.
+   */
+  [catalogVar: `EMAIL_MESSAGES_${string}`]: unknown;
+  BASE_URL: string;
+  // ENVIRONMENT is inherited from SecretsStoreEnv (a `ManagedEnvironment`); never redeclare it as a plain string.
+  LINK_TTL_DAYS?: string;
+  MAX_ATTEMPTS?: string;
+  SCHEDULER_ENABLED?: string;
+  SCHEDULER_BATCH_SIZE?: string;
+  SCHEDULER_MAX_JOBS?: string;
+  SCHEDULER_GRACE_MS?: string;
+  SCHEDULER_STUCK_MS?: string;
+}
+
+// This is a standalone worker, not assembled by `createBackend`, so the secrets capability's `compose`
+// hook never runs here. Configure the shared per-invocation accessor directly from email's own slice so
+// `resolveSigningKeys` reads the signing key through the one cached path.
+configureSharedSecrets({ registry: emailSigningRegistry });
+
+/** The dispatch door. Built once per isolate; the environment gate reads its answer per request. */
+const app = createEmailHostApp();
+
+/**
+ * The env, parsed — or one legible block naming every unusable setting and what fills it, then a
+ * refusal. Called at the top of every entry, and the block is written once per env object.
+ */
+function hostConfig(env: EmailWorkerEnv): EmailHostEnv {
+  return requireHostEnv(emailHostEnv, env);
+}
+
+/** Assemble the send dependencies, resolving the current signing key from the secrets store. */
+async function buildSendDeps(env: EmailWorkerEnv): Promise<SendBatchDeps> {
+  const config = hostConfig(env);
+  const keys = await resolveSigningKeys(env);
+  const key = keys.versions[keys.currentVersion];
+  return {
+    db: emailDatabase(env.DB),
+    suppressionDb: emailSuppressionDatabase(env.EMAIL_SUPPRESSIONS),
+    sender: env.EMAIL,
+    theme: config.EMAIL_THEME,
+    // The catalogs, as a seam over the one JSON var. A body renders in the job's own locale from here;
+    // with the var absent this resolves to the kit's English, unchanged from before #441.
+    layersFor: catalogLayers(catalogsFromEnv(env as unknown as Record<string, unknown>)),
+    baseUrl: config.BASE_URL,
+    signing: key ? { key, kid: keys.currentVersion } : undefined,
+    linkTtlDays: config.LINK_TTL_DAYS,
+    maxAttempts: config.MAX_ATTEMPTS,
+    environment: config.ENVIRONMENT,
+    heartbeatAt: () => new Date(),
+  };
+}
+
+/** Assemble the scheduler dependencies, dispatching each batch as a send Workflow. */
+function buildSchedulerDeps(env: EmailWorkerEnv): SchedulerDeps {
+  const config = hostConfig(env);
+  return {
+    db: emailDatabase(env.DB),
+    now: new Date(),
+    graceMs: config.SCHEDULER_GRACE_MS,
+    stuckMs: config.SCHEDULER_STUCK_MS,
+    batchSize: config.SCHEDULER_BATCH_SIZE,
+    maxJobs: config.SCHEDULER_MAX_JOBS,
+    // The same mint as the other two dispatchers, so the three cannot drift into three id schemes.
+    newBatchId: mintBatchId,
+    // The batch's id is the instance's id, so this is the whole of the lookup. A rejection means the
+    // instance is not there to ask — a dispatch that never landed — and that is stranded, not alive: the
+    // answer may only ever veto a re-drive, so the cautious reading is the one that keeps recovering.
+    batchIsAlive: async (batchId) => {
+      try {
+        const instance = await env.EMAIL_SENDER.get(batchId);
+        const { status } = await instance.status();
+        return isLiveInstanceStatus(status);
+      } catch {
+        return false;
+      }
+    },
+    dispatch: async (batchId, jobIds) => {
+      await env.EMAIL_SENDER.create({ id: batchId, params: { jobIds } });
+    },
+  };
+}
+
+/**
+ * Sends a batch of jobs durably. Started for immediate sends and by the scheduler's fan-out.
+ *
+ * Every step runs under {@link emailWorkflowRetry}, which agrees with `errorMapping.ts` by
+ * construction: a rate limit and a transient provider fault re-drive the job, and a template that does
+ * not exist, a payload that will not render, or a job row that is gone fail it at once. See
+ * `send/retryPolicy.ts`.
+ */
+export class EmailSendWorkflow extends WorkflowEntrypoint<EmailWorkerEnv, { jobIds: string[] }> {
+  // The batch report is the instance's output (#380). A job whose step spent its retries is contained
+  // so the rest of the batch still sends, and this is where an operator reads which ones those were —
+  // beside the failed step in the same instance. It carries job ids and outcomes, never a recipient.
+  override async run(event: WorkflowEvent<{ jobIds: string[] }>, step: WorkflowStep): Promise<BatchSendReport> {
+    return await runSendBatch(
+      await buildSendDeps(this.env),
+      classifiedSteps(step, emailWorkflowRetry, NonRetryableError),
+      event.payload.jobIds,
+    );
+  }
+}
+
+/** Finds due jobs and fans them out into send batches. Fired by the every-minute cron. */
+export class EmailSchedulerWorkflow extends WorkflowEntrypoint<EmailWorkerEnv, unknown> {
+  override async run(_event: WorkflowEvent<unknown>, step: WorkflowStep): Promise<void> {
+    await classifiedSteps(step, emailWorkflowRetry, NonRetryableError).do("dispatch-due", async () => {
+      await runScheduler(buildSchedulerDeps(this.env));
+    });
+  }
+}
+
+export default {
+  /** Cron entry: fire the scheduler Workflow every minute, unless disabled. */
+  async scheduled(_controller: unknown, env: EmailWorkerEnv): Promise<void> {
+    if (hostConfig(env).SCHEDULER_ENABLED) {
+      await env.EMAIL_SCHEDULER.create();
+    }
+  },
+
+  /**
+   * The loopback dispatch door — how a sibling worker under `pithy dev` starts a send batch on this
+   * host's own same-script Workflow binding (pithy-sh/pithy#410). Refused in every other environment,
+   * where the cross-script binding is the only path in.
+   *
+   * The env is validated before the router sees the request: a host that cannot work must not accept
+   * a dispatch and then lose it. The refusal is `core/internal` and the block is already in the log,
+   * which is what its action line points the operator at.
+   */
+  async fetch(request: Request, env: EmailWorkerEnv, ctx: ExecutionContext): Promise<Response> {
+    hostConfig(env);
+    return await app.fetch(request, env, ctx);
+  },
+};