@pithy-sh/email 0.1.0

package/src/templates/severity.ts

@@ -0,0 +1,102 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * How urgent an operational notice is, and how that urgency is said out loud.
+ *
+ * **Severity is words first and color second, and the order matters.** A notice is read in an inbox
+ * list before it is opened, in a plain-text client that has no colors at all, and by people who cannot
+ * tell the red one from the amber one. So each level owns a *label* — which goes in the subject line,
+ * in the body, and in the text part — and a color that only ever reinforces it. A design where the
+ * only difference between "a release is out" and "your sign-in is broken" is a hex value has flattened
+ * them, and a reader who cannot see the difference learns to ignore both.
+ *
+ * The labels name the response, not the volume. "Action needed" tells somebody what the message wants
+ * from them; "Warning" only tells them how loudly it is being said.
+ */
+
+export const NoticeSeverity = z
+  .enum(["info", "warning", "critical"])
+  .describe(
+    "How urgent an operational notice is. `info` is something that happened and needs nothing (a release is out); `warning` is something that needs attention before it becomes a fault (a secret is overdue for rotation); `critical` is something that is failing now. The level sets the subject-line label, so it is visible in an inbox before the message is opened.",
+  );
+export type NoticeSeverity = z.output<typeof NoticeSeverity>;
+
+/** One severity's presentation: the key its word is looked up under, and the color that reinforces it. */
+interface SeverityPresentation {
+  /**
+   * The catalog key holding the word — in the subject line, the body, and the text part.
+   *
+   * A key rather than the word itself, because the word is the half of this table that changes with the
+   * reader. The colors below do not: an accent belongs to a brand and "this is on fire" belongs to
+   * everyone, so they stay literals here while the label goes through `email/severity.*` in the
+   * catalog. `messages.ts` writes the English; `@pithy-sh/i18n` ships the rest.
+   */
+  labelKey: string;
+  /** The light-mode color, applied inline. Contrast-checked against the card white every preset uses. */
+  light: string;
+  /** The dark-mode color, swapped in by class under `prefers-color-scheme: dark`. */
+  dark: string;
+}
+
+/**
+ * The one place a severity's presentation is decided.
+ *
+ * Colors are fixed rather than themed, deliberately: an accent belongs to a brand, but "this is on
+ * fire" belongs to the reader. A project whose accent is red would otherwise render a routine notice
+ * in the color of an emergency. Both ramps are contrast-checked — the light values against the white
+ * card every preset ships, the dark values against the near-black one.
+ */
+const PRESENTATION = {
+  info: { labelKey: "email/severity.info", light: "#475467", dark: "#98A2B3" },
+  warning: { labelKey: "email/severity.warning", light: "#B54708", dark: "#FEC84B" },
+  critical: { labelKey: "email/severity.critical", light: "#B42318", dark: "#FDA29B" },
+} as const satisfies Record<NoticeSeverity, SeverityPresentation>;
+
+/**
+ * The presentation for a value that has already been through {@link NoticeSeverity}.
+ *
+ * A template renders after its payload is parsed, so the value is always one of the three. The
+ * fallback exists because a Handlebars helper must return *something* and `info` is the only safe
+ * guess: a notice that renders as calmer than it is can still be read, while one that throws mid-render
+ * is the notice nobody receives.
+ */
+function presentationOf(severity: unknown): SeverityPresentation {
+  // `Object.hasOwn`, not `in`: `in` walks the prototype, so `severity === "constructor"` would answer
+  // true and hand back `Object` itself. Unreachable today — the payload is `NoticeSeverity`-parsed
+  // before a render — but it is the same read the i18n lookups were fixed for, and one site left
+  // spelled the other way is the one somebody copies.
+  return typeof severity === "string" && Object.hasOwn(PRESENTATION, severity)
+    ? PRESENTATION[severity as NoticeSeverity]
+    : PRESENTATION.info;
+}
+
+/**
+ * The catalog key holding the word this level is called.
+ *
+ * The engine's `{{severityLabel severity}}` helper resolves this through the render's translator, so
+ * the level is said in the recipient's language in all three places it appears. Exported as a key and
+ * not as a word, because a function returning a word would have to be handed a translator, and then
+ * every caller would carry one to ask a question about an enum.
+ */
+export function severityLabelKey(severity: unknown): string {
+  return presentationOf(severity).labelKey;
+}
+
+/** The `{{severityColor severity}}` helper: the light-mode color, applied inline like every other one. */
+export function severityColor(severity: unknown): string {
+  return presentationOf(severity).light;
+}
+
+/**
+ * The dark-mode overrides for the severity colors, generated from the same table.
+ *
+ * The shared head partial carries the light values inline and swaps these in under
+ * `prefers-color-scheme: dark`, exactly as it does for the theme's own palette. Generated rather than
+ * written out so a color changed here cannot leave dark mode showing the old one.
+ */
+export const severityDarkModeCss: string = Object.entries(PRESENTATION)
+  .map(([name, { dark }]) => `    .sev-${name} { color: ${dark} !important; }`)
+  .join("\n");

package/src/templates/theme.ts

@@ -0,0 +1,212 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The theme injected into every template: "plug your colors in, point at your logo." Templates render
+ * with full **light/dark** support — each mode has its own background, card, text, and separator
+ * colors, applied inline for light and swapped in via a `prefers-color-scheme: dark` style block. A
+ * single `accent` (saffron) carries through both modes. Visual polish is deliberately secondary to the
+ * typed payload contracts — this is enough to brand the starter set well.
+ */
+
+export const ContentWidth = z
+  .enum(["narrow", "wide"])
+  .describe(
+    "The email body width: `narrow` (600px — the transactional default) or `wide` (720px — better for newsletters).",
+  );
+export type ContentWidth = z.output<typeof ContentWidth>;
+
+/** One mode's color set — the surfaces and text shades the templates reference. */
+export const Palette = z
+  .object({
+    background: z.string().describe("The page background behind the card."),
+    cardBackground: z.string().describe("The card surface the email content sits on."),
+    text: z.string().describe("The primary text/heading color."),
+    textMuted: z.string().describe("Secondary body text — summaries, supporting copy."),
+    textSubtle: z.string().describe("Tertiary text — the footer and fine print."),
+    separator: z.string().describe("The hairline rule color between sections."),
+  })
+  .describe("A light- or dark-mode color set for the email templates.");
+export type Palette = z.output<typeof Palette>;
+
+/** A footer link (social or otherwise). */
+export const FooterLink = z
+  .object({
+    label: z.string().describe("The link text shown in the footer."),
+    href: z.string().describe("The absolute URL the footer link points to."),
+  })
+  .describe("One footer link rendered in the email footer.");
+export type FooterLink = z.output<typeof FooterLink>;
+
+export const EmailTheme = z
+  .object({
+    appName: z.string().describe("The product name shown in the header (when no logo is set) and the footer."),
+    accent: z
+      .string()
+      .describe(
+        "The single accent color (hex) for the CTA button and the header rule, in both modes. Defaults to saffron.",
+      ),
+    logoUrl: z.string().describe("Absolute URL of the light-mode header logo PNG. Empty renders the app name as text."),
+    logoDarkUrl: z
+      .string()
+      .describe(
+        "Absolute URL of the dark-mode logo PNG, swapped in under `prefers-color-scheme: dark`. Empty falls back to the light logo / app name.",
+      ),
+    footerAddress: z
+      .string()
+      .describe("The physical mailing address shown in the footer — required for marketing (CAN-SPAM) compliance."),
+    light: Palette.describe("The light-mode color set, applied inline."),
+    dark: Palette.describe("The dark-mode color set, applied via a `prefers-color-scheme: dark` style block."),
+    links: z.array(FooterLink).describe("Footer links (e.g. social profiles), rendered as a separated row."),
+  })
+  .describe("Brand theme for the email templates — light/dark palettes, accent, logo, and the compliance footer.");
+export type EmailTheme = z.output<typeof EmailTheme>;
+
+/**
+ * A partial override of {@link EmailTheme} — the thin config surface a project tweaks. Every field is
+ * optional and deep-merges over the chosen preset, so `customTheme: { accent: "#7C3AED", dark: { background: "#0A0A0A" } }`
+ * changes just those values and inherits the rest. Body width is **not** here: it is a property of the
+ * template (transactional is narrow, newsletters wide), not the brand.
+ */
+export const CustomTheme = EmailTheme.partial()
+  .extend({
+    // Override `light`/`dark` with *partial* palettes so a project can change one color, not the whole set.
+    // The scalar fields + `links` are inherited (as optional) from EmailTheme, so this can never drift from it.
+    light: Palette.partial().optional().describe("Override individual light-mode palette colors."),
+    dark: Palette.partial().optional().describe("Override individual dark-mode palette colors."),
+  })
+  .describe("A partial, deep-merged override of the chosen theme preset — derived from EmailTheme so it can't drift.");
+export type CustomTheme = z.output<typeof CustomTheme>;
+
+/** A named, off-the-shelf palette pair plus its accent — the base a config picks and may override. */
+export interface ThemePalettes {
+  accent: string;
+  light: Palette;
+  dark: Palette;
+}
+
+/**
+ * Off-the-shelf themes a project can pick by name to bootstrap its config (`email({ theme: "midnight" })`),
+ * then override piecemeal (`accent`, `light`, `dark`). Each ships a matched light/dark pair so dark mode
+ * looks intentional, not auto-inverted. `saffron` is the Pithy default.
+ */
+export const themePresets = {
+  /** Pithy brand — warm parchment/ink, saffron accent. */
+  saffron: {
+    accent: "#D4A017",
+    light: {
+      background: "#FAFAF6",
+      cardBackground: "#FFFFFF",
+      text: "#111111",
+      textMuted: "#5F5D57",
+      textSubtle: "#9A988F",
+      separator: "#E7E5DF",
+    },
+    dark: {
+      background: "#14110D",
+      cardBackground: "#1C1813",
+      text: "#FAFAF6",
+      textMuted: "#A09C90",
+      textSubtle: "#6B675E",
+      separator: "#2A251E",
+    },
+  },
+  /** Cool, modern neutral with a blue accent — a safe SaaS default. */
+  midnight: {
+    accent: "#3B82F6",
+    light: {
+      background: "#F4F6FB",
+      cardBackground: "#FFFFFF",
+      text: "#0F172A",
+      textMuted: "#475569",
+      textSubtle: "#94A3B8",
+      separator: "#E2E8F0",
+    },
+    dark: {
+      background: "#0B1120",
+      cardBackground: "#111827",
+      text: "#F1F5F9",
+      textMuted: "#94A3B8",
+      textSubtle: "#64748B",
+      separator: "#1E293B",
+    },
+  },
+  /** Calm green — good for product/community mail. */
+  forest: {
+    accent: "#2F9E6E",
+    light: {
+      background: "#F3F7F4",
+      cardBackground: "#FFFFFF",
+      text: "#13231B",
+      textMuted: "#4B6358",
+      textSubtle: "#8AA597",
+      separator: "#DDE8E1",
+    },
+    dark: {
+      background: "#0C140F",
+      cardBackground: "#141F18",
+      text: "#ECF5EF",
+      textMuted: "#9CB6A7",
+      textSubtle: "#5F7568",
+      separator: "#213028",
+    },
+  },
+  /** Warm rose — softer, friendlier for consumer/lifecycle mail. */
+  rose: {
+    accent: "#E0567A",
+    light: {
+      background: "#FBF4F6",
+      cardBackground: "#FFFFFF",
+      text: "#26101A",
+      textMuted: "#6B4451",
+      textSubtle: "#B08A95",
+      separator: "#F0DDE3",
+    },
+    dark: {
+      background: "#160C10",
+      cardBackground: "#20141A",
+      text: "#F8EEF1",
+      textMuted: "#C29AA6",
+      textSubtle: "#7A5662",
+      separator: "#33222A",
+    },
+  },
+} satisfies Record<string, ThemePalettes>;
+
+/** The names of the off-the-shelf themes. */
+export type ThemePreset = keyof typeof themePresets;
+
+/** The default theme — Pithy brand (`saffron`), parchment/ink light, deep-ink dark, logo-less. */
+export const defaultTheme: EmailTheme = {
+  appName: "Pithy",
+  accent: themePresets.saffron.accent,
+  logoUrl: "",
+  logoDarkUrl: "",
+  footerAddress: "",
+  light: themePresets.saffron.light,
+  dark: themePresets.saffron.dark,
+  links: [],
+};
+
+/** Build a full {@link EmailTheme} from a preset plus an optional partial override (deep-merged). */
+export function resolveTheme(preset: ThemePreset, custom?: CustomTheme): EmailTheme {
+  const base = themePresets[preset];
+  const merged: EmailTheme = {
+    appName: custom?.appName ?? defaultTheme.appName,
+    accent: custom?.accent ?? base.accent,
+    logoUrl: custom?.logoUrl ?? "",
+    logoDarkUrl: custom?.logoDarkUrl ?? "",
+    footerAddress: custom?.footerAddress ?? "",
+    light: { ...base.light, ...custom?.light },
+    dark: { ...base.dark, ...custom?.dark },
+    links: custom?.links ?? [],
+  };
+  return merged;
+}
+
+/** The pixel width the layout uses for a given content width. */
+export function widthPx(width: ContentWidth): number {
+  return width === "wide" ? 720 : 600;
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/email knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/email";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";

package/src/workflows/hostApp.ts

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { AmbientEnv } from "@pithy-sh/core/src/env/ambient";
+import { pithyErrorHandler } from "@pithy-sh/core/src/error/http";
+import { registerWorkflowDispatchRoute } from "@pithy-sh/core/src/workflow/dispatchRoute";
+import { Hono } from "hono";
+import { EMAIL_CAPABILITY } from "../provision/provisionEmail";
+import { emailWorkflowRegistry } from "../provision/resolveEmailConfig";
+
+/**
+ * The email host worker's HTTP surface: one route, and only in `dev`.
+ *
+ * The host had no `fetch` at all — it was reached by Workflow dispatch and its cron, and nothing
+ * else. That is still true of a deployed environment: an app worker holds a cross-script
+ * `EMAIL_SENDER` binding and never speaks HTTP to this Worker. Locally there is no such binding,
+ * because `pithy dev` runs each worker as its own `wrangler dev` and CLAUDE.md rules out wrangler's
+ * cross-process service registry. So `pithy dev` composes a loopback dispatcher instead, pointed at
+ * `EMAIL_ORIGIN`, and this is the door it knocks on (pithy-sh/pithy#410).
+ *
+ * Everything about the route — the environment gate, the `public` verification strategy, the request
+ * contract, the 202 — belongs to `@pithy-sh/core/src/workflow/dispatchRoute`, so the other eight
+ * capability hosts mount the identical thing. What is email's is the registry: `:binding` resolves
+ * against email's own two jobs, and the payload validates against the declaring spec's schema.
+ *
+ * Built here rather than inside `worker.ts` because that module imports `cloudflare:workers` and so
+ * cannot be loaded under node. This one can, which is what lets the wiring be tested without a
+ * Workers runtime — and the wiring is the part that was missing.
+ */
+
+/** What the app needs to know beyond its registry: where it is running. */
+export interface EmailHostAppOptions {
+  /**
+   * The ambient environment the dispatch gate reads. Defaults to the process env, which in a Worker
+   * is the script's own vars — where provisioning stamps `ENVIRONMENT`. Injectable for tests.
+   */
+  env?: AmbientEnv;
+}
+
+/** Build the email host worker's app: the Pithy error handler, and the workflow dispatch route. */
+export function createEmailHostApp(options: EmailHostAppOptions = {}): Hono<PithyHonoEnv> {
+  const app = new Hono<PithyHonoEnv>();
+  // The same handler every composed Pithy app mounts, so a refusal on this door renders as a
+  // `PithyError` on the wire rather than as a stack trace the loopback dispatcher would report as an
+  // unreadable body.
+  app.onError(pithyErrorHandler);
+  registerWorkflowDispatchRoute(app, {
+    capability: EMAIL_CAPABILITY,
+    registry: emailWorkflowRegistry,
+    env: options.env,
+  });
+  return app;
+}

package/src/workflows/hostEnv.ts

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { defineHostEnv, type HostEnvProvider } from "@pithy-sh/core/src/workflow/hostEnv";
+import type { SecretBinding } from "@pithy-sh/secrets/src/env/bindings";
+import { z } from "zod";
+import type { EmailSender } from "../send/sender";
+import { defaultTheme, EmailTheme } from "../templates/theme";
+import type { SendWorkflowInstances } from "./instances";
+
+/**
+ * What the prebuilt email host worker reads out of its env — declared once, validated at boot, and
+ * read statically by `pithy doctor` (pithy-sh/pithy#410, #411).
+ *
+ * Nobody authors this Worker. `pithy email provision` resolves the committed template beside this
+ * file and deploys it, so every value here arrives as a binding, a var or a Secrets Store entry that
+ * a *machine* wrote — and until this module, none of it was checked. Three failures, all of them
+ * discovered as mail that did not arrive:
+ *
+ *   - `BASE_URL` absent → every magic link in the batch pointed at `undefined/auth/…`.
+ *   - `EMAIL_THEME` unparseable → a `JSON.parse` threw inside a render step, three retries deep,
+ *     where the message reads as a template fault.
+ *   - `SCHEDULER_BATCH_SIZE` written `"fifty"` → `Number(...)` gave `NaN`, the scheduler claimed
+ *     nothing, and it did so on every tick, forever, without a line in the log.
+ *
+ * So the parse is the boot check: `z.output` is what the host actually runs on, which is why the
+ * coercions live in the schema rather than at the call sites. `Number(env.MAX_ATTEMPTS ?? 5)` in
+ * `worker.ts` was the shape of the bug — a default and a coercion restated at every reader, each free
+ * to disagree with the next.
+ *
+ * ## Two names, deliberately
+ *
+ * {@link EmailHostEnv} is the schema (and the type the host runs on). {@link emailHostEnv} is the
+ * *declaration*: the schema plus what fills each field, which is the object the CLI imports. The
+ * second is the one an operator's report is built from — a missing field is only actionable when
+ * something names the binding, var or command that writes it.
+ *
+ * Node-safe on purpose. No `cloudflare:` import and no filesystem, so `pithy doctor` can import this
+ * without executing the Worker — the same constraint `@pithy-sh/core`'s host modules carry.
+ */
+
+/** The command that writes every provisioned value here. Stated once so nine action lines cannot drift. */
+const PROVISION = "pithy email provision --env <env>";
+
+/** A binding `pithy email provision` wires into the resolved `wrangler.jsonc`. */
+const binding = (name: string): HostEnvProvider => ({ kind: "binding", name, command: PROVISION });
+
+/** A var the same run stamps into that config's `vars` block. */
+const provisionedVar = (name: string): HostEnvProvider => ({ kind: "var", name, command: PROVISION });
+
+/** A var with a shipped default — the template carries it, and an adopter may tune it in place. */
+const tunedVar = (name: string): HostEnvProvider => ({ kind: "var", name });
+
+/**
+ * A binding the host calls one method on, checked structurally.
+ *
+ * Duck-typed rather than `instanceof`-checked because these are host objects the runtime hands over:
+ * there is no class to compare against, and `wrangler dev`'s stand-ins are different objects again.
+ * What the host depends on is the method, so the method is what is asserted.
+ */
+function callable<T>(method: string, what: string): z.ZodType<T> {
+  return z.custom<T>((value) => typeof (value as Record<string, unknown> | null | undefined)?.[method] === "function", {
+    error: `${what} — the binding is missing, or it is not the kind of binding this name expects.`,
+  });
+}
+
+/** A D1 binding. `prepare` is the whole of what Kysely's D1 dialect needs from one. */
+const d1Binding = (what: string): z.ZodType<D1Database> => callable<D1Database>("prepare", what);
+
+/**
+ * A count or a duration wrangler binds as a string.
+ *
+ * `z.coerce` before the integer check, so `"50"` is fifty and `"fifty"` is a refusal naming the field
+ * — which is precisely the difference between this and the `Number(...)` it replaces.
+ */
+const tunedNumber = (fallback: number) => z.coerce.number().int().positive().default(fallback);
+
+/** The email host's env, as the host runs on it. Every field is coerced here, never at its reader. */
+export const EmailHostEnv = z
+  .object({
+    DB: d1Binding("The app database holding this environment's email jobs and events").describe(
+      "The app D1 database. The `pithy_email_jobs` and `pithy_email_events` tables live here, beside the adopter's own data. Bound by `pithy email provision`, which fills the id for the environment being deployed.",
+    ),
+    EMAIL_SUPPRESSIONS: d1Binding("The shared suppression database every environment of this project binds").describe(
+      "The durable suppression D1 database — one per project, bound identically in every environment, so an unsubscribe or a hard bounce applies everywhere the project sends from. Named `<project>-global-email-suppressions`.",
+    ),
+    SECRETS: d1Binding("The per-environment secrets database the link-signing key is read from").describe(
+      "The per-environment secrets D1 database. The link-signing key is stored here as an encrypted row and read through `@pithy-sh/secrets`; without it, tracking and unsubscribe links cannot be signed.",
+    ),
+    SECRETS_ENCRYPTION_KEYS: z
+      .union([z.string().min(1), callable<SecretBinding>("get", "The master key binding")])
+      .describe(
+        "The master key that decrypts the secrets database — a Cloudflare Secrets Store binding in a deployed environment, and the same name as a plain string in `.dev.vars` locally. The one secret read outside the `secretsStore` accessor, because it is what makes the accessor work.",
+      ),
+    EMAIL: callable<EmailSender>("send", "The Cloudflare Email Service send binding").describe(
+      "The Cloudflare Email Service `send_email` binding — the only thing in the kit that puts a message on the wire. `wrangler dev` simulates it locally; `remote: true` (the default under `pithy dev`) sends for real from the developer's machine.",
+    ),
+    EMAIL_SENDER: z
+      .custom<EmailSenderBinding>((value) => isCallable(value, "create") && isCallable(value, "get"), {
+        error: "The send Workflow binding — it must both start an instance and answer about one.",
+      })
+      .describe(
+        "This host's own send Workflow, same-script. Two calls, and both matter: `create` starts a batch, and `get` is how the scheduler asks whether the instance a stranded row names is still alive before re-driving it.",
+      ),
+    EMAIL_SCHEDULER: callable<{ create(): Promise<unknown> }>("create", "The scheduler Workflow binding").describe(
+      "This host's own scheduler Workflow, same-script. Fired by the every-minute cron; it finds due jobs and fans them out into send batches.",
+    ),
+    BASE_URL: z
+      .url()
+      .describe(
+        "The app worker's public base URL for this environment. Every link that leaves in an email — magic link, tracked click, unsubscribe — is built against it, so a wrong value is a message that arrives and cannot be acted on.",
+      ),
+    EMAIL_THEME: z
+      .string()
+      .optional()
+      .transform((raw, ctx): unknown => {
+        if (raw === undefined || raw.trim().length === 0) return defaultTheme;
+        try {
+          return JSON.parse(raw) as unknown;
+        } catch {
+          ctx.addIssue({ code: "custom", message: "Not valid JSON. The whole theme travels as one JSON var." });
+          return z.NEVER;
+        }
+      })
+      // Parsed, then validated: an unreadable theme must fail here, at boot, and not inside a render
+      // step three retries deep where the message reads as a broken template.
+      .pipe(EmailTheme)
+      .describe(
+        "The resolved brand theme, serialized as one JSON var at provision from the adopter's `email()` config. Absent falls back to the kit's default theme; present-and-unreadable is refused.",
+      ),
+    ENVIRONMENT: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "The environment this host was deployed for. Stamped on every send as `X-Pithy-Env`, which is how the single inbound bounce worker attributes a bounce back to the environment that sent it.",
+      ),
+    LINK_TTL_DAYS: tunedNumber(90).describe(
+      "How long a signed tracking or unsubscribe link stays valid, in days. Long by design: the link is minted into mail nobody can recall, and an unsubscribe that has expired is a complaint.",
+    ),
+    MAX_ATTEMPTS: tunedNumber(5).describe(
+      "How many times one job may be attempted before it is failed terminally. Spent attempts are what separates a provider hiccup from an address that will never accept mail.",
+    ),
+    SCHEDULER_ENABLED: z
+      .enum(["true", "false"])
+      .describe("The var as wrangler binds it — a string, and only these two spellings of it.")
+      .default("true")
+      .transform((value) => value === "true")
+      .describe(
+        "Whether the every-minute scheduler Workflow runs. `false` stops due jobs being claimed at all — the cron still fires and does nothing — so it is a maintenance switch, not a tuning knob.",
+      ),
+    SCHEDULER_BATCH_SIZE: tunedNumber(50).describe(
+      "How many jobs one send Workflow instance takes. Each job is a durable step, so this is the unit of retry and of the instance's report.",
+    ),
+    SCHEDULER_MAX_JOBS: tunedNumber(500).describe(
+      "The most rows one scheduler tick will claim. A ceiling on the work a single minute can start, so a backlog drains steadily rather than in one instance-creating burst.",
+    ),
+    SCHEDULER_GRACE_MS: tunedNumber(2 * 60_000).describe(
+      "How long an immediate job is left alone before the safety net treats it as stranded, in milliseconds. The window a freshly-enqueued job's own dispatch has to land in; too short re-drives sends that were already on their way.",
+    ),
+    SCHEDULER_STUCK_MS: tunedNumber(15 * 60_000).describe(
+      "How long a job may sit `sending` before the safety net re-drives it, in milliseconds. A send Workflow in retry backoff writes nothing, so this is what tells a slow batch apart from a dead one.",
+    ),
+  })
+  .describe("Everything the prebuilt email host worker reads out of its env, in the shape it runs on.");
+export type EmailHostEnv = z.output<typeof EmailHostEnv>;
+
+/** The send Workflow binding as the host holds it: it starts instances and answers about them. */
+type EmailSenderBinding = {
+  create(options: { id?: string; params: { jobIds: string[] } }): Promise<unknown>;
+} & SendWorkflowInstances;
+
+/** Whether a value carries a callable method of that name. */
+function isCallable(value: unknown, method: string): boolean {
+  return typeof (value as Record<string, unknown> | null | undefined)?.[method] === "function";
+}
+
+/**
+ * The email host's env declaration — the schema plus what fills each field.
+ *
+ * The host validates against this at boot ({@link import("@pithy-sh/core/src/workflow/hostEnv").requireHostEnv});
+ * `pithy doctor` walks the same object to check an adopter's *resolved* settings without running a
+ * Worker. One declaration, so the check an operator runs and the check the host runs cannot disagree.
+ */
+export const emailHostEnv = defineHostEnv({
+  capability: "email",
+  env: EmailHostEnv,
+  provided: {
+    DB: binding("DB"),
+    EMAIL_SUPPRESSIONS: binding("EMAIL_SUPPRESSIONS"),
+    SECRETS: binding("SECRETS"),
+    SECRETS_ENCRYPTION_KEYS: {
+      kind: "secret",
+      name: "SECRETS_ENCRYPTION_KEYS",
+      command: "pithy secrets provision --env <env>",
+    },
+    EMAIL: binding("EMAIL"),
+    EMAIL_SENDER: binding("EMAIL_SENDER"),
+    EMAIL_SCHEDULER: binding("EMAIL_SCHEDULER"),
+    BASE_URL: provisionedVar("BASE_URL"),
+    // Written from the adopter's own `email()` config, so the fix is in `pithy.config.ts` and only
+    // then in a provision run. Named as the config key, because that is where a person edits it.
+    EMAIL_THEME: { kind: "config", name: "email({ theme, customTheme })", command: PROVISION },
+    // The catalogs are deliberately absent from this map and from the schema above. Their variable
+    // *names* are the project's locales — `EMAIL_MESSAGES_ES`, `EMAIL_MESSAGES_PT_BR` — and neither a
+    // Zod object nor a fixed declaration table can name a key that is a decision made downstream.
+    // `catalogsFromEnv` collects them off the raw env and validates each value; a missing one is not a
+    // fault, because a project that serves only English has none to carry.
+    ENVIRONMENT: provisionedVar("ENVIRONMENT"),
+    LINK_TTL_DAYS: tunedVar("LINK_TTL_DAYS"),
+    MAX_ATTEMPTS: tunedVar("MAX_ATTEMPTS"),
+    SCHEDULER_ENABLED: tunedVar("SCHEDULER_ENABLED"),
+    SCHEDULER_BATCH_SIZE: tunedVar("SCHEDULER_BATCH_SIZE"),
+    SCHEDULER_MAX_JOBS: tunedVar("SCHEDULER_MAX_JOBS"),
+    SCHEDULER_GRACE_MS: tunedVar("SCHEDULER_GRACE_MS"),
+    SCHEDULER_STUCK_MS: tunedVar("SCHEDULER_STUCK_MS"),
+  },
+});

package/src/workflows/instanceLiveness.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What a Workflow instance's status means to the scheduler (pithy-sh/pithy#342).
+ *
+ * The scheduler re-drives a `sending` job only when the batch holding it is not alive, and "alive" is a
+ * question about a Workflow instance rather than about a row. This is the one statement of which answers
+ * count as alive — kept out of `worker.ts` because that module imports `cloudflare:workers` and can
+ * therefore only be exercised by deploying it, and this is a rule worth driving.
+ */
+
+/**
+ * The statuses that mean "this batch is still coming".
+ *
+ * Named as the live set rather than the dead one, deliberately. A status the platform adds tomorrow then
+ * reads as dead and its jobs are re-driven — the safety net erring towards recovery, which costs a
+ * duplicate render that `runSend` short-circuits for anything already `sent` — instead of this code
+ * silently vouching for an instance state it has never heard of.
+ *
+ * `queued` is live because the instance exists and will start. `paused` is live because a paused
+ * instance is resumable and still owns its rows; re-driving one would put a second Workflow behind the
+ * same jobs and make pausing a batch a way to send everyone in it twice.
+ *
+ * Outside it today: `errored`, `terminated`, `complete`, and anything unrecognized. None of those will
+ * touch another job, so whatever they left in `sending` is genuinely stranded.
+ */
+const LIVE_INSTANCE_STATUSES: ReadonlySet<string> = new Set([
+  "queued",
+  "running",
+  "paused",
+  "waiting",
+  "waitingForPause",
+]);
+
+/** Does this instance status mean the batch is still coming? */
+export function isLiveInstanceStatus(status: string): boolean {
+  return LIVE_INSTANCE_STATUSES.has(status);
+}

package/src/workflows/instances.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The half of the Workflows binding that answers about an instance already created.
+ *
+ * Declared here rather than taken from `cloudflare:workers` because the scheduler must not depend on
+ * the platform types — it takes a question as a function, and only the host answers it with a real
+ * Workflow. It lives in its own module rather than beside that host because `workflows/worker.ts`
+ * imports `cloudflare:workers` and so cannot be loaded under node, while
+ * {@link ./hostEnv.ts} — which `pithy doctor` imports — has to be.
+ */
+export interface SendWorkflowInstances {
+  /** Look an instance up by the id it was created with. Rejects when no such instance exists. */
+  get(id: string): Promise<{ status(): Promise<{ status: string }> }>;
+}