@pithy-sh/email 0.1.0

package/src/jobs/retry.ts

@@ -0,0 +1,214 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { normalizeAddress } from "@pithy-sh/core/src/address/address";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { ConflictError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import type { EmailJob } from "../data/emailJob";
+import type { EmailDatabase, EmailSuppressionDatabase } from "../data/tables";
+import { EmailSuppressedError } from "../error/errors";
+import { mintBatchId } from "../send/batchIdentity";
+import type { SendWorkflowBinding } from "../send/enqueue";
+import { blockingSuppression } from "../send/suppression";
+import { templateKind } from "../templates/engine";
+import { getJob } from "./read";
+
+/**
+ * Putting a failed job back in the queue — the body behind `POST /email/jobs/:id/retry`.
+ *
+ * ## A handler never sends
+ *
+ * `runSend` is Workflow-only and is never called from here. A retry does what `enqueueEmail` does: it
+ * puts the row back into a sendable state and dispatches the send Workflow. That keeps the one place
+ * that talks to the Email Service inside a durable step with retries and history, which is the whole
+ * reason email is a job table rather than a function call.
+ *
+ * A failed dispatch is safe and deliberately swallowed. The row is `pending` before the Workflow is
+ * started, so the every-minute scheduler's safety net re-drives it on the next tick — the same contract
+ * `enqueueEmail` relies on. Losing the dispatch costs a minute; failing the request after the row was
+ * already reset would tell an operator nothing happened when something did.
+ *
+ * ## Only a `failed` job may be retried
+ *
+ * Every other state is refused with `core/conflict`, and each refusal is a different thing going wrong:
+ *
+ * - `sent` — already delivered. Retrying is a duplicate email to a real person. It is also the one
+ *   state whose inputs are gone: a transactional job's payload is dropped when the message goes out,
+ *   which is safe precisely because this refusal is what makes `sent` terminal.
+ * - `pending` / `scheduled` / `sending` — still in flight. Resetting it races the scheduler, and
+ *   `sending` in particular is a job a Workflow is holding right now.
+ * - `suppressed` — the address is on the block list. Retrying is the one send this capability must
+ *   never make.
+ * - `bounced` — the recipient's server said permanently no, and the bounce handler only sets this
+ *   state while suppressing the address, so a retry is the previous case wearing a different label.
+ * - `canceled` — somebody withdrew it. Reviving a withdrawal is a separate decision, not a retry, and
+ *   it should have to be made somewhere it is named.
+ *
+ * ## The attempt budget is reset, and it has to be
+ *
+ * `runSend` gives up when `attempts >= maxAttempts`. A job that failed did so having spent its budget,
+ * so a retry that left `attempts` alone would take one retryable error to fail terminally again — the
+ * button would appear to work and change nothing. `attempts` returns to zero; `error` does not, because
+ * it is the record of what went wrong last time and a successful send clears it anyway.
+ *
+ * ## The batch id is re-minted, and the old one must not survive
+ *
+ * A `failed` row still names the batch that failed it (pithy-sh/pithy#342), and that id is about to
+ * become wrong in both directions at once. `batchId` means *the instance coming for this row* — see
+ * `send/batchIdentity.ts` — and after a retry the instance coming for it is the one this function
+ * starts, not the one that gave up on it.
+ *
+ * Leaving the old id there is not a stale label. It hands the scheduler's veto the wrong Workflow to ask
+ * about, and a failure inside a batch is exactly the case where that Workflow is *still running*: a
+ * batch of fifty that failed job seven walks on to job fifty. So the tick that should re-drive the retry
+ * asks about the batch that abandoned it, is told "alive", and holds — the operator's click sends
+ * nothing for as long as the old batch runs. Then the old batch ends, the same row reads as stranded,
+ * and the tick starts a second Workflow behind the one this function already started. Held when it
+ * should send, then sent twice: one wrong id, both failures.
+ *
+ * So a retry mints its own, writes it in the same statement that makes the row queryable again, and
+ * creates the instance under it. Null when there is no binding to dispatch on, because then nothing is
+ * coming for the row and the scheduler should claim it on the next tick — and the row is `undispatched`
+ * rather than `pending` there, for the reason the write itself states.
+ */
+
+/** What a retry needs: both databases, the send Workflow binding, and the clock. */
+export interface RetryDeps {
+  /** The per-environment jobs database. */
+  db: EmailDatabase;
+  /** The global suppression database — checked before the row is touched. */
+  suppressionDb: EmailSuppressionDatabase;
+  /**
+   * The send Workflow binding. Optional so a Worker that somehow lacks it still resets the row and
+   * leaves the scheduler to re-drive, rather than failing an operator's click outright.
+   */
+  sender?: SendWorkflowBinding;
+  now: Date;
+  /**
+   * Mint the id of the batch this retry dispatches — **the send Workflow instance's id**
+   * (pithy-sh/pithy#342). Defaults to {@link mintBatchId}; injected only so a test can name it.
+   */
+  newBatchId?: () => string;
+}
+
+/** What a retry did. */
+export interface RetryResult {
+  /** The job that was re-queued. */
+  job: EmailJob;
+  /**
+   * Whether the send Workflow actually started. False means the scheduler will pick the row up within
+   * the minute — the mail is not lost, it is merely not immediate.
+   */
+  dispatched: boolean;
+}
+
+/**
+ * Re-queue one failed job.
+ *
+ * Reads before it writes: the job must exist, be `failed`, and its recipient must not have been
+ * suppressed in the meantime. That last check is not redundant with `runSend`'s — `runSend` would mark
+ * the row `suppressed` and skip, which reports to the operator as a successful retry that silently sent
+ * nothing. Refusing here says what actually happened.
+ */
+export async function retryJob(deps: RetryDeps, jobId: string): Promise<RetryResult> {
+  const existing = await getJob(deps.db, jobId);
+  if (!existing) {
+    throw new NotFoundError({
+      message: "No such email job.",
+      action: "Check the job id against the send log.",
+      detail: `email job '${jobId}' not found`,
+    });
+  }
+
+  if (existing.status !== "failed") {
+    throw new ConflictError({
+      message: `Only a failed job can be retried. This one is ${existing.status}.`,
+      action: "Retry a job whose status is failed.",
+      detail: `email job '${jobId}' is ${existing.status}`,
+    });
+  }
+
+  const recipient = normalizeAddress(existing.toAddress);
+  // Asked the same way `runSend` asks it, kind included. An operator retrying a failed magic link to
+  // somebody who unsubscribed from a newsletter must not be told the address is unreachable — the send
+  // would go through, so refusing it here would be this capability inventing a block of its own.
+  const blocked = await blockingSuppression(deps.suppressionDb, recipient, deps.now, templateKind(existing.template));
+  if (blocked) {
+    throw new EmailSuppressedError({
+      message: `That recipient is on the suppression list (${blocked}), so this job cannot be retried.`,
+      action: "Remove the address from the suppression list first, if that is what you mean to do.",
+      detail: `recipient of email job '${jobId}' is suppressed: ${blocked}`,
+    });
+  }
+
+  // The batch this retry will start, named before the row is written so the same statement that makes
+  // the row queryable again also says who is coming for it. Null with no binding: nothing is.
+  const batchId = deps.sender ? (deps.newBatchId ?? mintBatchId)() : null;
+
+  const updated = await deps.db
+    .updateTable("pithyEmailJobs")
+    .set({
+      // **The failed batch's id does not survive the retry** — see the note above. Whether it is
+      // re-minted or nulled, what must not happen is the row keeping the id of the batch that gave up on
+      // it, because that batch is usually still running and its liveness would be read as this row's.
+      batchId,
+      // `pending`, whatever the original mode was. A retry is an operator asking for this to go now;
+      // re-arming a `scheduled` job to a `sendAt` that is already in the past would say the same thing
+      // less clearly, and re-deriving a `timezone` job's local slot would move the send to tomorrow.
+      //
+      // With no binding it is `undispatched` instead — the same word `enqueueEmail` writes for the very
+      // same env (pithy-sh/pithy#410). One deployment must not have two names for one configuration
+      // fact: `pending` here would tell an operator their click queued a send while an enqueue two
+      // lines away was recording that this composition can start none. The scheduler claims either, so
+      // the retry is deferred and not dropped.
+      status: deps.sender ? "pending" : "undispatched",
+      sendAt: SQLiteDate.encode(deps.now),
+      attempts: 0,
+      updatedAt: SQLiteDate.encode(deps.now),
+      // **`createdAt` is reset too, and it is load-bearing.** The scheduler's safety net for an
+      // immediate job is `status = 'pending' AND createdAt <= now - graceMs`, and that grace exists so a
+      // job that has just been dispatched by whoever wrote it is not re-dispatched while its own
+      // Workflow is still starting. A retried row's original `createdAt` is by definition old, so
+      // leaving it would give the row *zero* grace: the next cron tick would claim it and dispatch a
+      // second send Workflow for a job this function had already dispatched successfully. `runSend`
+      // short-circuits only on `sent`/`canceled`, so both instances would render and send, and the
+      // recipient would get two copies. Re-stamping it puts the retry inside the same window a fresh
+      // enqueue gets, which is exactly what a retry is.
+      createdAt: SQLiteDate.encode(deps.now),
+    })
+    .where("id", "=", jobId)
+    // Status is in the predicate, not merely checked above, which makes this a compare-and-set rather
+    // than a read followed by a hopeful write. Two people pressing retry on the same visible failure is
+    // the ordinary case here, and without it the loser would reset a row the winner's Workflow had
+    // already claimed and then dispatch a second send of the same email.
+    .where("status", "=", "failed")
+    .executeTakeFirst();
+
+  if ((updated.numUpdatedRows ?? 0n) === 0n) {
+    // Somebody else re-queued it between the read and the write. Refused with the same words the state
+    // check above uses, because it is the same refusal — the job is simply no longer failed.
+    const current = await getJob(deps.db, jobId);
+    throw new ConflictError({
+      message: `Only a failed job can be retried. This one is ${current?.status ?? "no longer there"}.`,
+      action: "Reload the send log — somebody may have retried it already.",
+      detail: `email job '${jobId}' left the failed state between the read and the write`,
+    });
+  }
+
+  let dispatched = false;
+  if (deps.sender && batchId) {
+    try {
+      // Under the id the row now carries. The claim is written first, so the instance can never be alive
+      // before the row can name it; the reverse order would leave a window in which a tick re-drives a
+      // job whose Workflow has already started.
+      await deps.sender.create({ id: batchId, params: { jobIds: [jobId] } });
+      dispatched = true;
+    } catch {
+      // Swallowed deliberately: the row is `pending` naming an instance that is not there, the runtime
+      // disowns it, and the every-minute scheduler owns recovery.
+    }
+  }
+
+  const job = (await getJob(deps.db, jobId)) ?? existing;
+  return { job, dispatched };
+}

package/src/migrations/0001_init.ts

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Create the per-environment email tables in the app database: `pithy_email_jobs` and
+ * `pithy_email_events`. Both carry the `pithy_email_` prefix so they never clash with an adopter's own
+ * tables. (Suppression lives in its own durable database — see `0001_suppressions.ts`.)
+ *
+ * Identifiers are declared in **camelCase**: the runner installs `CamelCasePlugin`, which snake-cases
+ * every identifier in the emitted DDL (CLAUDE.md §Data layer). `down` is the tested inverse — indexes
+ * then tables, in reverse creation order (D1 has no transactional DDL).
+ *
+ * **This is the capability's whole schema for this database, in one migration, and that is the rule
+ * while nothing is published.** CONTRIBUTING.md §Migrations states it and
+ * `packages/cli/src/migrations/oneMigration.test.ts` enforces it: a chain buys exactly one thing —
+ * walking a database that already holds rows from an old shape to a new one — and there is no such
+ * database, so a `0002` would be a step from a shape that never ran to a shape that never shipped.
+ *
+ * **Amended in place on 2026-08-23** for `locale` (pithy-sh/pithy#441), and **on 2026-08-16** for
+ * `correlation` (pithy-sh/pithy#382). The condition was re-checked on each occasion rather than
+ * assumed, because CONTRIBUTING.md asks a later reader to check it:
+ *
+ * - `@pithy-sh/email` is at `0.0.0` and `npm view @pithy-sh/email version` is a 404. Nothing has been
+ *   released, so no `0200_email_0001_init` has run anywhere a chain would be replayed against.
+ * - The only adopter is `pithy-sh/dashboard`, and `GET /accounts/602df2e6ce74e98b4c7ac5e90a3af5c8/d1/database`
+ *   — the account `apps/board/pithy.config.ts` pins, not whatever wrangler is logged in to — returns an
+ *   **empty list**. There is no deployed D1 at all, so none holds a `pithy_email_jobs` row.
+ *
+ * **The moment either stops being true this file is history, and the chain is append-only.** A version
+ * cut, or one database on that account, and the next column is a `0002`. Nothing about a tidy `0001`
+ * tells a reader which side of that line they are on — re-run the two checks, do not infer them.
+ */
+export const email_0001_init: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyEmailJobs")
+      .addColumn("id", "text", (c) => c.primaryKey())
+      .addColumn("toAddress", "text", (c) => c.notNull())
+      // The recipient under `normalizeAddress`, stored rather than derived. `toAddress` keeps the
+      // string the caller typed; this is what anything matching a recipient compares against, and
+      // `lower(to_address)` is not a substitute — SQLite's `lower()` folds ASCII only.
+      .addColumn("recipientKey", "text", (c) => c.notNull())
+      .addColumn("fromAddress", "text", (c) => c.notNull())
+      .addColumn("fromName", "text", (c) => c.notNull())
+      .addColumn("subject", "text", (c) => c.notNull())
+      .addColumn("template", "text", (c) => c.notNull())
+      .addColumn("category", "text", (c) => c.notNull())
+      .addColumn("payload", "text", (c) => c.notNull())
+      // Null while the job still holds its inputs; stamped when they are dropped. A separate column
+      // rather than an inference off `payload = '{}'`, because a job enqueued with no variables and a
+      // job whose variables were spent are different facts and an operator reading a blank render needs
+      // to tell them apart.
+      .addColumn("payloadRedactedAt", "integer")
+      .addColumn("status", "text", (c) => c.notNull())
+      .addColumn("mode", "text", (c) => c.notNull())
+      .addColumn("attempts", "integer", (c) => c.notNull().defaultTo(0))
+      // The send batch holding this job, which is the id of the send Workflow instance dispatched for
+      // it. Null until something claims the job. Unindexed on purpose: nothing queries by it — the
+      // scheduler reads it off rows it has already selected and asks the Workflow runtime about them.
+      .addColumn("batchId", "text")
+      .addColumn("sendAt", "integer", (c) => c.notNull())
+      .addColumn("timezone", "text")
+      .addColumn("localTime", "text")
+      .addColumn("campaignId", "text")
+      // The language this message is written in, as a BCP-47 tag. Null means nobody chose one, and the
+      // render falls back to the kit's English — which is not the same statement as `en`, exactly as
+      // `pithy_auth_users.locale` distinguishes them.
+      //
+      // On the row rather than re-derived at send, and that is the whole of pithy-sh/pithy#441 for this
+      // table. The subject is rendered at enqueue, inside a request that knows the reader; the body is
+      // rendered hours later inside a Workflow that has no request at all. Two renders, two chances to
+      // choose a language, and until this column they could only agree by accident. It is also what a
+      // support pane needs to answer "why did this letter arrive in Spanish" — an operator reading a
+      // subject they cannot parse otherwise has nothing on the row that explains it.
+      .addColumn("locale", "text")
+      // What the message was *about*, as the caller names it — the discriminator for a template that
+      // carries more than one kind of message (pithy-sh/pithy#382). Six of the dashboard's account
+      // notices ride one `operationalNotice` to the same addresses, so `(recipient_key, template)`
+      // cannot separate them and `sentSince` could not answer the question it was built for. And the
+      // failure was not a duplicate: that caller uses the answer *positively* — the correction letter
+      // goes out only when the letter it corrects already did — so an under-report withholds the
+      // correction from somebody holding a letter that has stopped being true.
+      //
+      // Nullable with no default, the shape `pithy_audit_events.tenant` takes for an action that was
+      // not tenant-scoped: most templates say what they are by their id alone, and null is the true
+      // statement about those. Deliberately **not** `campaign_id`, which is marketing attribution and
+      // leaves this row — onto every event, into `campaignStats`, and signed into the tracking token
+      // that travels in a delivered email's URLs. This column goes nowhere but here.
+      .addColumn("correlation", "text")
+      .addColumn("openTracking", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("clickTracking", "integer", (c) => c.notNull().defaultTo(0))
+      .addColumn("messageId", "text")
+      .addColumn("error", "text")
+      .addColumn("bounceCode", "text")
+      .addColumn("bounceType", "text")
+      // Threading, for a reply that answers an existing conversation — `@pithy-sh/support` is what
+      // needs them. A column per field rather than a generic headers bag (CLAUDE.md §Email): a bag
+      // would let any caller set `Bcc` or `From` on a message the adopter's domain signs, which turns
+      // an enqueue into a header-injection surface. Three named columns can only mean three things.
+      .addColumn("replyTo", "text")
+      .addColumn("inReplyTo", "text")
+      .addColumn("references", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("updatedAt", "integer", (c) => c.notNull())
+      .addColumn("sentAt", "integer")
+      .execute();
+
+    // The scheduler scans for due rows by (status, sendAt); the bounce handler looks a job up by its
+    // Email Service messageId.
+    await db.schema.createIndex("pithyEmailJobsDueIdx").on("pithyEmailJobs").columns(["status", "sendAt"]).execute();
+    await db.schema.createIndex("pithyEmailJobsMessageIdIdx").on("pithyEmailJobs").column("messageId").execute();
+
+    await db.schema
+      .createTable("pithyEmailEvents")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("jobId", "text", (c) => c.notNull())
+      .addColumn("recipient", "text", (c) => c.notNull())
+      .addColumn("type", "text", (c) => c.notNull())
+      .addColumn("linkLabel", "text")
+      .addColumn("linkUrl", "text")
+      .addColumn("campaignId", "text")
+      .addColumn("detail", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .execute();
+
+    await db.schema.createIndex("pithyEmailEventsJobIdIdx").on("pithyEmailEvents").column("jobId").execute();
+
+    // The control-plane job listing pages newest-first, optionally filtered by status. `(status,
+    // createdAt)` serves the filtered page and `createdAt` alone the unfiltered one — without them an
+    // operator opening the pane scans every job the project has ever queued.
+    await db.schema
+      .createIndex("pithyEmailJobsStatusCreatedIdx")
+      .on("pithyEmailJobs")
+      .columns(["status", "createdAt"])
+      .execute();
+    await db.schema.createIndex("pithyEmailJobsCreatedIdx").on("pithyEmailJobs").column("createdAt").execute();
+
+    // `sentSince` asks one question — has this template already gone to this person since a given
+    // instant — and asks it of a table holding every email the project ever queued. Without this the
+    // question is a full scan, and it is asked on the path that decides whether to send another one.
+    // Leading with the recipient rather than the template is what makes it selective: a project has a
+    // handful of templates and an unbounded number of recipients.
+    await db.schema
+      .createIndex("pithyEmailJobsRecipientTemplateIdx")
+      .on("pithyEmailJobs")
+      .columns(["recipientKey", "template", "createdAt"])
+      .execute();
+
+    // The other axis of the same read, and the same argument. `sentSince` also asks *what has been said
+    // about this thing since an instant* — the question a template carrying six different messages needs
+    // — and without an index that is the same full scan on the same decision path. It leads with
+    // `correlation` because a correlation names one subject and is selective by construction, where a
+    // template id is one of a handful a project has.
+    await db.schema
+      .createIndex("pithyEmailJobsCorrelationIdx")
+      .on("pithyEmailJobs")
+      .columns(["correlation", "createdAt"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyEmailJobsCorrelationIdx").execute();
+    await db.schema.dropIndex("pithyEmailJobsRecipientTemplateIdx").execute();
+    await db.schema.dropIndex("pithyEmailJobsCreatedIdx").execute();
+    await db.schema.dropIndex("pithyEmailJobsStatusCreatedIdx").execute();
+    await db.schema.dropIndex("pithyEmailEventsJobIdIdx").execute();
+    await db.schema.dropTable("pithyEmailEvents").execute();
+    await db.schema.dropIndex("pithyEmailJobsMessageIdIdx").execute();
+    await db.schema.dropIndex("pithyEmailJobsDueIdx").execute();
+    await db.schema.dropTable("pithyEmailJobs").execute();
+  },
+};

package/src/migrations/0001_suppressions.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Create the global suppression table in the dedicated, durable `EMAIL_SUPPRESSIONS` database —
+ * distinct from the per-environment app `DB`, because an address that hard-bounced, complained, or
+ * unsubscribed must never be emailed from *any* environment. Mirrors the shared-DB pattern of
+ * `@pithy-sh/secrets`. The single inbound bounce worker and the unsubscribe callbacks write it; every
+ * environment's send path reads it.
+ */
+export const email_0001_suppressions: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyEmailSuppressions")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("email", "text", (c) => c.notNull().unique())
+      .addColumn("reason", "text", (c) => c.notNull())
+      .addColumn("jobId", "text")
+      .addColumn("environment", "text")
+      .addColumn("detail", "text")
+      .addColumn("createdAt", "integer", (c) => c.notNull())
+      .addColumn("expiresAt", "integer")
+      .execute();
+
+    // The control-plane suppression listing pages newest-first. The unique index on `email` already
+    // serves the single-address lookup; this serves the walk.
+    await db.schema
+      .createIndex("pithyEmailSuppressionsCreatedIdx")
+      .on("pithyEmailSuppressions")
+      .column("createdAt")
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyEmailSuppressionsCreatedIdx").execute();
+    await db.schema.dropTable("pithyEmailSuppressions").execute();
+  },
+};

package/src/provision/devDelivery.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * How mail leaves the email host worker when that worker is running on a developer's machine.
+ *
+ * The point of the local loop is a magic link that **arrives** (pithy-sh/pithy#410). Until now it
+ * could not: `pithy dev` never ran the email host at all, so a sign-in wrote a row that said
+ * `pending` and a screen that said "check your inbox". With the host in the dev set, one flag decides
+ * what its `send_email` binding does — and the default is the one that ends the loop.
+ *
+ * Both settings run the Worker locally. Neither is a transport of ours: `wrangler dev` implements the
+ * binding either way, and there is no REST or SMTP sender in this kit (that stays out of scope until
+ * a context with no binding at all needs one).
+ */
+
+/** What the host's `send_email` binding does under `pithy dev`. */
+export const DevMailDelivery = z
+  .enum(["remote", "simulator"])
+  .describe(
+    "How email is delivered when the host worker runs under `pithy dev`. **`remote` is the default, and it sends real mail from the developer's machine** — `remote: true` on the `send_email` binding runs the Worker locally and delivers through Cloudflare Email Service, so the message lands in a real inbox with the same DKIM and the same delivery logs as production. It needs a Cloudflare login `wrangler dev` can use and a sending domain already onboarded onto Email Service. `simulator` sends nothing: `wrangler dev` logs the sender, recipient and subject and writes the rendered HTML and text bodies to disk, which is what an offline machine and CI want. Choose `simulator` deliberately — the cost of `remote` is that a test sign-in really does reach whatever address it was given.",
+  );
+export type DevMailDelivery = z.infer<typeof DevMailDelivery>;
+
+/** The local environment. The only one this flag governs; every other one deploys and delivers for real. */
+const DEV_ENVIRONMENT = "dev";
+
+/** The `send_email` binding name the committed host template declares. */
+const SEND_BINDING = "EMAIL";
+
+/**
+ * Which bindings the resolved host config must mark `remote: true`, for one environment.
+ *
+ * The committed template no longer hardcodes the flag, because a hardcoded `true` cannot be turned
+ * off: `resolveWorkflowHost` only ever *adds* `remote`, so a template that already carried it left no
+ * way to select the simulator. The decision moved here, where the capability's config can reach it.
+ *
+ * Outside `dev` the answer is always `remote: true`. A deployed Worker ignores the flag entirely —
+ * it is a `wrangler dev` instruction — so the resolved config for `staging` and `prod` is byte-
+ * identical whatever an adopter chose for their laptop.
+ */
+export function emailRemoteBindings(env: string, delivery: DevMailDelivery): readonly string[] {
+  if (env === DEV_ENVIRONMENT && delivery === "simulator") return [];
+  return [SEND_BINDING];
+}

package/src/provision/hostCatalogs.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { KitErrorPayload } from "@pithy-sh/core/src/error/payload";
+import type { LocaleCatalogs, MessageCatalog } from "@pithy-sh/core/src/i18n/catalog";
+import { EMAIL_MESSAGES, type EmailMessageLayers } from "../templates/messages";
+
+/**
+ * The catalogs the prebuilt email host worker is deployed with — the provision-time half of
+ * `catalogLayers`.
+ *
+ * ## Why the host needs data where the app worker needs a seam
+ *
+ * An app worker composes capabilities, so `@pithy-sh/email`'s enqueue reaches a composed project's
+ * `layersFor` through the `compose` hook and renders a subject in whatever language the project
+ * speaks. The host worker composes nothing: `pithy email provision` deploys it from a committed
+ * template, and no `pithy.config.ts` of the adopter's is ever evaluated inside it. So the layers
+ * cannot travel as a function; they travel as one JSON var, and this is what flattens them.
+ *
+ * Nothing wrote that var before pithy-sh/pithy#441's remediation, which made the whole translated-body
+ * path dead in any real deployment: the send Workflow rendered the kit's English whatever tag was on
+ * the row, and — because `runSend` overwrites the stored subject with its own fresh render — discarded
+ * the translated subject the app worker had computed at enqueue as well. Two Workers, one message, and
+ * they disagreed about its language.
+ *
+ * ## What is dropped, and why dropping it changes nothing
+ *
+ * **Only `email/` keys.** The host renders email templates and nothing else, so a screen's copy or an
+ * error's translation in this var is weight against a hard 5 KB ceiling (see `resolveEmailConfig`) for
+ * a key no template will ever ask for.
+ *
+ * **And only keys that say something the host does not already have.** `catalogLayers` ends every
+ * lookup at `EMAIL_MESSAGES` — this package's own copy, in every language it is written in, bundled
+ * into the host — so a key whose merged value is byte-identical to what the host already resolves for
+ * that locale renders the same string whether it is in the var or not. Leaving it out is invisible in
+ * the rendered mail, and it is what makes adding a language cost no configuration at all: a project
+ * on the kit's own locales that overrode nothing deploys no catalog variable.
+ *
+ * An adopter who overrode a sentence is unaffected, including one who overrode a translation back to
+ * the English wording: the comparison is against the locale's own bundled value, which is not that.
+ */
+
+/** The domain every key this capability renders lives under — `composeMessages` enforces it too. */
+const EMAIL_KEY_PREFIX = "email/";
+
+/**
+ * The `email/*` keys that are **error codes**, not template copy.
+ *
+ * The prefix alone is not the rule the doc below states. `email/send_failed` and its five siblings are
+ * catalog keys under this capability's domain because for an error the key *is* the code — but no
+ * template ever asks for one, and the host is the Worker that renders templates. A client translates
+ * an error from a catalog it already holds; the send Workflow never renders one.
+ *
+ * Worth the derivation rather than a list: it is 416 bytes of a 5120-byte ceiling that a real project
+ * already fills to 69%, so it is roughly 8% of the room a second locale would need. Read off
+ * `KitErrorPayload` so a seventh `email/*` code drops out on its own.
+ */
+const EMAIL_ERROR_CODES: ReadonlySet<string> = new Set(
+  KitErrorPayload.options.map((member) => member.shape.code.value).filter((code) => code.startsWith(EMAIL_KEY_PREFIX)),
+);
+
+/** Whether a key is copy this host will actually render. */
+function rendersOnTheHost(key: string): boolean {
+  return key.startsWith(EMAIL_KEY_PREFIX) && !EMAIL_ERROR_CODES.has(key);
+}
+
+/**
+ * Flatten a composed project's layers into the `EMAIL_MESSAGES` var's value, one catalog per locale.
+ *
+ * `locales` is the project's `supportedLocales`; a project that composed no i18n capability passes
+ * none, gets `{}`, and deploys a host with no var at all — which is the same English it always sent.
+ */
+export function emailHostCatalogs(locales: readonly string[], layersFor: EmailMessageLayers): LocaleCatalogs {
+  const catalogs: LocaleCatalogs = {};
+  for (const locale of locales) {
+    const merged: MessageCatalog = {};
+    // The layers arrive most-specific first, because that is the order `lookupMessage` walks them in.
+    // Flattening runs the other way: the least specific lands first and the adopter's override writes
+    // over it, so the value left standing is the one `t()` would have found.
+    for (const layer of [...layersFor(locale)].reverse()) {
+      for (const [key, value] of Object.entries(layer ?? {})) {
+        if (rendersOnTheHost(key)) merged[key] = value;
+      }
+    }
+    // **What travels is the adopter's diff, and nothing else (#442).**
+    //
+    // The host is deployed carrying `EMAIL_MESSAGES` — the kit's own copy in every language it is
+    // written in — so a key whose merged value is already what the host holds for this locale is a
+    // sentence it would render identically with no variable at all. Sending it is sending the Worker
+    // words it was built with.
+    //
+    // It used to be compared against the English alone, which meant the kit's own Spanish rode along:
+    // static data through a configuration channel, every provision run, against a 5 KB per-variable
+    // ceiling that a language pack filled to 61%. Compared against the locale's own bundled copy, a
+    // project that overrides nothing deploys no variable, and adding a language the kit ships costs no
+    // configuration growth at all.
+    //
+    // The English fallback stays in the comparison because that is what the host renders for a key no
+    // translation covers — dropping only against the locale would send back every untranslated key.
+    const bundled = { ...(EMAIL_MESSAGES.en ?? {}), ...(EMAIL_MESSAGES[locale] ?? {}) };
+    for (const [key, value] of Object.entries(merged)) {
+      if (bundled[key] === value) delete merged[key];
+    }
+    if (Object.keys(merged).length > 0) catalogs[locale] = merged;
+  }
+  return catalogs;
+}