@pithy-sh/email 0.1.0

package/src/provision/provisionEmail.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
+import { resourceName } from "@pithy-sh/core/src/naming/resource";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/src/scope";
+
+/**
+ * The provisioning orchestration for the email capability — the live counterpart to `pithy add email`'s
+ * config wiring. It stands up the durable infrastructure the rest of the capability assumes: the
+ * suppression database (one per **project**, bound by every one of that project's environments) and the
+ * per-environment prebuilt email worker that hosts the send + scheduler Workflows and the every-minute
+ * cron.
+ *
+ * Unlike `@pithy-sh/secrets`, the email worker needs **no minted CF API token** — it sends through the
+ * Cloudflare Email Service `send_email` binding and reads its signing key through the `SECRETS` bindings,
+ * neither of which uses an API token. So provisioning here is purely: create + migrate the suppression
+ * DB, then deploy each environment's worker.
+ *
+ * The live Cloudflare/wrangler steps are behind the {@link EmailProvisioner} seam, so the orchestration
+ * (order, idempotency contract, per-env fan-out) is unit-tested without touching Cloudflare; the real
+ * seam implementation is the live-CF glue, exercised by the integration suite. Every step is idempotent —
+ * re-running provisioning is a no-op.
+ *
+ * **Operator prerequisites (out of band, like the secrets store):** the sending domain must be onboarded
+ * onto Cloudflare Email Service, one Email Routing rule must point bounce/complaint mail at the production
+ * app worker, and the link-signing key must exist (`pithy secrets create email-link-signing-key`). These
+ * are one-time account/DNS actions provisioning does not own.
+ */
+
+/** The capability segment every email-owned name carries — the migration namespace and error domain too. */
+export const EMAIL_CAPABILITY = "email";
+
+/**
+ * The shared, durable suppression database — **one per project, shared across that project's
+ * environments**: `<project>-global-email-suppressions`.
+ *
+ * The sharing across environments is deliberate and load-bearing. "Do not email this person again" is
+ * not an environment-local fact; an address that hard-bounced in production must not be retried from
+ * staging, or the sending domain's reputation pays for the distinction. `global` sits in the
+ * environment slot to say so out loud rather than by omission.
+ *
+ * The sharing across **projects** was not deliberate — it was the absence of a project segment. D1's
+ * namespace is account-wide and provisioning reuses a database it finds by name, so a fixed
+ * `pithy-email-suppressions` meant a second, unrelated Pithy product in the same account silently
+ * inherited the first's opt-out list: one product's unsubscribe suppressing another product's
+ * transactional mail, with no row anywhere recording why. The project segment gives the scope a
+ * definition instead of an accident.
+ *
+ * Composed through core's naming facade under the **`d1`** namespace, so the name is measured against
+ * a D1 database name's limit rather than the single 63 the generic composer defaults to.
+ */
+export function suppressionDatabaseName(project: string): string {
+  return resourceNames(project).global.d1(`${EMAIL_CAPABILITY}-suppressions`);
+}
+
+/**
+ * The name of the inbound Email Routing rule that delivers bounce and complaint mail to the app worker.
+ *
+ * `global` in the environment slot because there is one rule per zone — the environments are separated
+ * by which app Worker the rule points at, not by the rule. Project-scoped and distinct from
+ * `@pithy-sh/support`'s `<project>-global-support-inbound`: `ensureWorkerRoute` keys idempotency on the
+ * rule *name*, so two projects sharing a zone under one unscoped name would each read the other's rule
+ * as their own, and one project's bounces would be delivered to the other's Worker.
+ *
+ * **The one name here still on the generic composer**, because an Email Routing rule is not a namespace
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for. The facade's whole point is
+ * that a kind of thing carries its own number; inventing one for this kind would be the opposite. So it
+ * takes the conservative default until that namespace lands.
+ */
+export function bounceRoutingRuleName(project: string): string {
+  return resourceName({ project, env: GLOBAL_SCOPE, thing: `${EMAIL_CAPABILITY}-bounce` });
+}
+
+/**
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
+ * through core's naming facade under the **`worker`** namespace (63, the workers.dev cap), which
+ * `resolveEmailConfig` also stamps onto the config: one source, so the name the CLI audits and deletes
+ * under cannot drift from the name it deploys under. The environment is validated on the way through,
+ * so a stale `production` fails here rather than deploying a second host beside the real one.
+ */
+export function emailWorkerName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).worker(EMAIL_CAPABILITY);
+}
+
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface EmailProvisioner {
+  /**
+   * Verify account prerequisites before any resource is created — most importantly a registered
+   * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting email worker.
+   * Throws a clear, actionable error so provisioning fails fast and clean rather than mid-deploy.
+   */
+  preflight(): Promise<void>;
+  /** Create (or reuse) the project's suppression D1; returns its id. Idempotent. Runs once, before any env. */
+  ensureSuppressionDatabase(): Promise<{ databaseId: string }>;
+  /** Run the `email_0001_suppressions` migration against the suppression D1. Idempotent (applied ones skip). */
+  migrateSuppression(databaseId: string): Promise<void>;
+  /** Deploy the prebuilt email worker for this environment, wired to the suppression DB and the env's own resources. */
+  deployWorker(env: ManagedEnvironment, suppressionDatabaseId: string): Promise<void>;
+  /**
+   * Ensure the inbound Email Routing rule that points bounce/complaint mail at the production app worker
+   * (one per domain). Idempotent. Returns `skipped: true` when no routing config is supplied — the
+   * routing target and inbound address are an operator choice (and must not disturb the apex MX), so a
+   * project that hasn't decided yet provisions everything else and adds the rule later.
+   */
+  ensureRoutingRule(): Promise<{ created: boolean; skipped: boolean }>;
+}
+
+/** What provisioning produced. */
+export interface EmailProvisionResult {
+  suppressionDatabaseId: string;
+  environments: ManagedEnvironment[];
+  /** Whether the inbound routing rule was created, already present, or skipped (not configured). */
+  routing: { created: boolean; skipped: boolean };
+}
+
+/**
+ * Provision the email infrastructure: create + migrate the shared suppression DB once, then deploy the
+ * email worker for every managed environment. The order matters — the suppression DB exists and is
+ * migrated before any worker that binds it is deployed. Idempotent end to end (each step is).
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function provisionEmail(
+  provisioner: EmailProvisioner,
+  environments: DeclaredEnvironments | readonly string[],
+): Promise<EmailProvisionResult> {
+  await provisioner.preflight();
+  const { databaseId } = await provisioner.ensureSuppressionDatabase();
+  await provisioner.migrateSuppression(databaseId);
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.deployWorker(env, databaseId);
+  }
+  // One inbound routing rule per domain (production app worker), after the workers are up.
+  const routing = await provisioner.ensureRoutingRule();
+  return { suppressionDatabaseId: databaseId, environments: managedEnvironments(environments), routing };
+}
+
+/** The teardown seam — the inverse of {@link EmailProvisioner}. Every step idempotent (a missing resource is a no-op). */
+export interface EmailDeprovisioner {
+  /** Delete the env's email worker. Idempotent (a missing worker is a no-op). */
+  deleteWorker(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Delete the shared suppression D1. **Destructive** — the global suppression list is lost, so every
+   * environment forgets who unsubscribed or hard-bounced — so the orchestration only calls it when
+   * explicitly asked. Idempotent.
+   */
+  deleteSuppressionDatabase(): Promise<void>;
+}
+
+/** Teardown options. By default the suppression DB is **kept** — losing the global opt-out list is harmful. */
+export interface EmailDeprovisionOptions {
+  /** Also delete the shared suppression database. Off by default; only a full destroy sets it. */
+  deleteSuppression?: boolean;
+}
+
+/**
+ * Tear down the email infrastructure, reversing {@link provisionEmail}: delete every environment's worker
+ * first (they bind the suppression DB), then — only when `deleteSuppression` is set — the shared
+ * suppression DB. The suppression list is preserved unless explicitly requested. Idempotent end to end.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function deprovisionEmail(
+  deprovisioner: EmailDeprovisioner,
+  environments: DeclaredEnvironments | readonly string[],
+  options: EmailDeprovisionOptions = {},
+): Promise<void> {
+  for (const env of managedEnvironments(environments)) {
+    await deprovisioner.deleteWorker(env);
+  }
+  if (options.deleteSuppression) await deprovisioner.deleteSuppressionDatabase();
+}

package/src/provision/resolveEmailConfig.ts

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import type {
+  HostD1Binding,
+  HostSecretsStoreBinding,
+  HostSendEmailBinding,
+  HostWorkflowBinding,
+  WorkflowHostTemplate,
+} from "@pithy-sh/core/src/workflow/host";
+import { hostWorkflowsFor, resolveWorkflowHost } from "@pithy-sh/core/src/workflow/host";
+import { workflowKey } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
+import { masterKeySecretName } from "@pithy-sh/secrets/src/provision/provisionSecrets";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { emailCatalogVarName } from "../templates/messages";
+import type { EmailTheme } from "../templates/theme";
+import { EmailScheduleParams, EmailSendParams } from "../workflows/params";
+import { type DevMailDelivery, emailRemoteBindings } from "./devDelivery";
+import { EMAIL_CAPABILITY, suppressionDatabaseName } from "./provisionEmail";
+
+/**
+ * The email worker's `wrangler.jsonc` template shape. Email invented the prebuilt-host convention;
+ * `@pithy-sh/core`'s {@link WorkflowHostTemplate} is the generalization of it, so this is now that
+ * contract with the fields email's committed template always carries narrowed to required. The
+ * committed template (`src/workflows/wrangler.jsonc`) stays the source of truth for the static fields
+ * (compatibility date, the every-minute cron, class names, the `send_email` binding, theme vars).
+ */
+export interface EmailWorkerWranglerTemplate extends WorkflowHostTemplate {
+  compatibility_date: string;
+  compatibility_flags: string[];
+  workers_dev: boolean;
+  d1_databases: HostD1Binding[];
+  send_email: HostSendEmailBinding[];
+  secrets_store_secrets: HostSecretsStoreBinding[];
+  workflows: HostWorkflowBinding[];
+  triggers: { crons: string[] };
+  vars: Record<string, string>;
+}
+
+/**
+ * The two durable jobs email's host runs, as a {@link WorkflowRegistry} — the shape
+ * {@link hostWorkflowsFor} derives project-scoped Workflow names from.
+ *
+ * Email declares these jobs on its `Capability` (`capability.ts`) rather than in a `workflows/specs.ts`
+ * the way every later capability does — it predates that convention. The host resolver needs a registry
+ * and cannot reach into a capability instance (building one requires an adopter's config), so the two
+ * jobs are mirrored here, and `resolveEmailConfig.test.ts` asserts the bindings and class names match
+ * the committed template byte for byte.
+ *
+ * **`params` is no longer a placeholder** (pithy-sh/pithy#410). The host mounts the shared dispatch
+ * route, and that route validates an arriving loopback payload against the declaring spec's own
+ * schema before it starts anything — so the registry's `params` is the request contract of a real
+ * HTTP surface. Both sides therefore read the one schema out of `workflows/params.ts`; a `z.unknown()`
+ * here would let a malformed dispatch through to fail inside a durable instance instead.
+ */
+const EMAIL_HOST_JOBS = {
+  send: { binding: "EMAIL_SENDER", className: "EmailSendWorkflow", params: EmailSendParams },
+  schedule: {
+    binding: "EMAIL_SCHEDULER",
+    className: "EmailSchedulerWorkflow",
+    params: EmailScheduleParams,
+    schedule: "* * * * *",
+  },
+} as const;
+
+/** The registry the host resolver derives its `workflows` array from, and the host's app dispatches on. */
+export const emailWorkflowRegistry: WorkflowRegistry = Object.fromEntries(
+  Object.entries(EMAIL_HOST_JOBS).map(([job, spec]) => {
+    const key = workflowKey(EMAIL_CAPABILITY, job);
+    return [key, { key, capability: EMAIL_CAPABILITY, job, spec }];
+  }),
+);
+
+/**
+ * The most one Cloudflare Worker variable holds. **Per variable, and that is the whole design.**
+ *
+ * Cloudflare's documented limit is 5 KB per variable, on Free and Paid alike, and a Worker carries 64
+ * of them on Free and 128 on Paid. The failure it produces is API error 10054 at upload — a wrangler
+ * exit nobody can act on, in the middle of a provision run that has already created databases.
+ *
+ * So each locale travels in its own variable. One pack of the kit's Spanish is about 3 KB, which
+ * leaves 2 KB of room inside its own ceiling, and twenty languages is twenty variables rather than one
+ * 62 KB value that is refused outright. The host renders one email in one locale and never needs the
+ * other nineteen, so nothing is paid for the split.
+ *
+ * The check below therefore guards what it should: a single language pack growing past what a variable
+ * holds, which would take the kit's email copy growing by about two thirds. It is deliberately a
+ * refusal and not a truncation — a shortened catalog is a letter half in Spanish and half in English,
+ * with nothing anywhere failing to say so.
+ */
+export const MAX_WORKER_VAR_BYTES = 5 * 1024;
+
+/**
+ * One `EMAIL_MESSAGES_<LOCALE>` var per locale, or nothing when the project has no catalogs to carry.
+ *
+ * A locale with an empty catalog is omitted rather than written as `"{}"`: the host reads an absent
+ * variable as the kit's English, which is exactly what that means, and an empty object in the deployed
+ * config reads like a value somebody failed to fill.
+ *
+ * **Exported because this is not the only host that carries them.** `@pithy-sh/testers`' daily-pass
+ * worker reads the same variables through the same `catalogsFromEnv` seam, against the same ceiling —
+ * so the limit, the naming and the refusal are composed here once rather than restated there, where
+ * the second copy is the one that drifts.
+ */
+export function emailMessagesVars(messages: LocaleCatalogs | undefined): Record<string, string> {
+  if (!messages) return {};
+  const vars: Record<string, string> = {};
+  for (const [locale, catalog] of Object.entries(messages)) {
+    if (!catalog || Object.keys(catalog).length === 0) continue;
+    const serialized = JSON.stringify(catalog);
+    const bytes = new TextEncoder().encode(serialized).length;
+    if (bytes > MAX_WORKER_VAR_BYTES) {
+      throw new ValidationError({
+        message: `The \`${locale}\` email catalog is ${bytes} bytes; a Cloudflare Worker variable holds ${MAX_WORKER_VAR_BYTES}.`,
+        action: `Shorten the \`email/\` sentences for \`${locale}\` in i18n({ messages }), or drop that locale from supportedLocales.`,
+        detail: `${emailCatalogVarName(locale)} serialized to ${bytes} bytes over the ${MAX_WORKER_VAR_BYTES}-byte limit; Cloudflare refuses the upload with error 10054.`,
+      });
+    }
+    vars[emailCatalogVarName(locale)] = serialized;
+  }
+  return vars;
+}
+
+/** The resolved resource ids + per-env values for one environment's email-worker deploy. */
+export interface EmailConfigParams {
+  /**
+   * The project name — the `<project>` segment the worker, both Workflows, and the suppression
+   * database name lead with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and
+   * never guessed: Worker script and Workflow names are account-scoped, so a wrong value here
+   * overwrites another project's running email host.
+   */
+  project: string;
+  /**
+   * The environment being resolved. `dev` as well as a deployed one: `pithy dev` resolves this same
+   * template into the local host config it runs, which is what {@link EmailConfigParams.devDelivery}
+   * governs.
+   */
+  env: ManagedEnvironment | "dev";
+  /** The app database id for this environment — where jobs/events live. */
+  appDatabaseId: string;
+  /** The shared suppression database id (same in every environment). */
+  suppressionDatabaseId: string;
+  /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the signing key. */
+  secretsDatabaseId: string;
+  /** The CF Secrets Store id holding the per-env master key. */
+  storeId: string;
+  /** The app worker's public base URL for this environment — callback links are built against it. */
+  baseUrl: string;
+  /** The resolved brand theme — serialized into the worker's `EMAIL_THEME` var. */
+  theme: EmailTheme;
+  /**
+   * This project's email catalogs — serialized into the worker's `EMAIL_MESSAGES` var.
+   *
+   * The same journey `theme` makes, and for the same reason: the host composes no capabilities, so
+   * anything the adopter configured has to arrive as data. `emailHostCatalogs` builds it from the
+   * composed project's layers; a project that composed no i18n capability passes `{}` or omits it, and
+   * the var is not written at all.
+   */
+  messages?: LocaleCatalogs;
+  /**
+   * What the host's `send_email` binding does under `pithy dev` — the adopter's `email({ devDelivery })`.
+   * Defaults to `remote`, which sends real mail from the developer's machine. Ignored outside `dev`.
+   */
+  devDelivery?: DevMailDelivery;
+  // No `schedulerEnabled`. `EmailConfig.schedulerEnabled` is parsed and exposed but never arrives
+  // here, so the template's hardcoded SCHEDULER_ENABLED="true" always wins — a known defect, filed
+  // rather than fixed, because closing it changes this signature and the provisioner's option bag,
+  // both of which are pinned by tests.
+}
+
+/**
+ * Resolve the email-worker `wrangler.jsonc` template into one environment's standalone config — no
+ * `[env.*]` stanzas (staging and prod are genuinely separate workers, per CLAUDE.md).
+ *
+ * The mechanics are `@pithy-sh/core`'s {@link resolveWorkflowHost}: this is the email-shaped face of
+ * it, mapping email's seven inputs onto the generic host params. What stays here is the part that is
+ * genuinely email's — which binding takes which database id, and the `@pithy-sh/secrets` import that
+ * names the env-scoped master key. Core must never depend on `@pithy-sh/secrets`, so the resolved
+ * string is passed in rather than the naming rule being hoisted.
+ *
+ * `send_email`'s `remote` flag is the one thing here that is a *decision* rather than a fill: real
+ * delivery is the default in every environment, and `dev` alone may choose the local simulator
+ * instead (`devDelivery.ts`).
+ *
+ * Only `EMAIL_SUPPRESSIONS`'s `database_name` is rewritten. That database is email's own, and its name
+ * now carries the project — leaving the template's `pithy-email-suppressions` in place would print a
+ * name no account holds. `pithy-app` and `pithy-secrets` are owned elsewhere and pass through
+ * untouched; only their ids differ per environment.
+ */
+export function resolveEmailConfig(
+  template: EmailWorkerWranglerTemplate,
+  params: EmailConfigParams,
+): EmailWorkerWranglerTemplate {
+  const { project, env, appDatabaseId, suppressionDatabaseId, secretsDatabaseId, storeId, baseUrl, theme } = params;
+  const resolved = resolveWorkflowHost(template, {
+    project,
+    capability: EMAIL_CAPABILITY,
+    env,
+    databaseIds: {
+      DB: appDatabaseId,
+      EMAIL_SUPPRESSIONS: suppressionDatabaseId,
+      SECRETS: secretsDatabaseId,
+    },
+    databaseNames: { EMAIL_SUPPRESSIONS: suppressionDatabaseName(project) },
+    secretsStoreId: storeId,
+    // The master key entry is project- and env-scoped, matching what the secrets manager wrote.
+    masterKeySecretName: masterKeySecretName(project, env),
+    // The theme and the catalogs travel the same way, and they have to: the host composes no
+    // capabilities, so the brand and the words are both things only a provision run can hand it.
+    vars: { EMAIL_THEME: JSON.stringify(theme), BASE_URL: baseUrl, ...emailMessagesVars(params.messages) },
+    // The `send_email` binding's `remote` flag, which the committed template deliberately no longer
+    // carries: the resolver only ever *adds* `remote`, so a hardcoded `true` could never be turned
+    // off and the documented simulator flag would have had nothing to act on. See `devDelivery.ts`.
+    remoteBindings: emailRemoteBindings(env, params.devDelivery ?? "remote"),
+    // Both Workflows, derived from the registry. A Workflow name is account-scoped, so the deployed
+    // name has to carry the project — the template's `pithy-email-send` cannot be suffixed into one.
+    workflows: hostWorkflowsFor(emailWorkflowRegistry, { project, capability: EMAIL_CAPABILITY, env }).workflows,
+  });
+  // The resolver fills fields; it never drops one. So every field this template narrows to required
+  // survives — knowledge the generic return type cannot express, restored here.
+  return resolved as EmailWorkerWranglerTemplate;
+}

package/src/provision/settingsCheck.ts

@@ -0,0 +1,212 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import type {
+  CapabilitySettings,
+  SettingsAccountContext,
+  SettingsCheckContext,
+  SettingsFinding,
+} from "@pithy-sh/core/src/capability/settings";
+import { hostEnvFindings } from "@pithy-sh/core/src/capability/settings";
+import { checkHostEnv } from "@pithy-sh/core/src/workflow/hostEnv";
+import { EMAIL_LINK_SIGNING_KEY } from "../crypto/signingKey";
+import type { EmailTheme } from "../templates/theme";
+import { emailHostEnv } from "../workflows/hostEnv";
+import { suppressionDatabaseName } from "./provisionEmail";
+
+/**
+ * Whether email's settings **work**, as `pithy doctor` asks it (pithy-sh/pithy#411).
+ *
+ * Every check doctor had before this one asked about presence: the `email({ … })` option keys are
+ * written, the `DB` and `EMAIL_SENDER` bindings are declared, the ledger is level. All of them pass while
+ * `fromAddress` names a domain nobody onboarded, the link-signing key was never created, `BASE_URL` is
+ * staging's URL in production's config, and the suppression database does not exist — and the way an
+ * adopter learns any of that is a message that never arrives.
+ *
+ * ## The local tier runs the host's own schema
+ *
+ * `checkHostEnv(emailHostEnv, …)` is not a second reading of the same rules — it is *the* reading. The
+ * prebuilt host worker refuses to start on the same declaration (`workflows/worker.ts`), so a value doctor
+ * calls good is a value the host will accept, and a rule that changes changes in one file. Bindings are
+ * stubbed on the way in, deliberately: whether `DB` is bound is `pithy doctor`'s `bindings` check and
+ * `Secret bindings:` block, and asking it twice would report one fault as two.
+ *
+ * ## The account tier asks the three things only the account knows
+ *
+ * Is the sending domain a zone here, does the suppression database exist, does the signing key have a
+ * value. Each costs one Cloudflare call, each is skipped whole when the account cannot be reached, and
+ * none of them is inferable from a file in the checkout.
+ *
+ * Nothing here writes. Every finding names the command, the config key, or the one-time dashboard action
+ * that resolves it.
+ */
+
+/** The resolved config slice the check reads. The capability builds it; nothing here parses config. */
+export interface EmailSettingsInput {
+  /** The address every message is sent from — its domain is what must be onboarded. */
+  fromAddress: string;
+  /** The public base URL every link in a message is built against. */
+  baseUrl: string;
+  /** The resolved theme, as the host receives it: one JSON var. */
+  theme?: EmailTheme;
+}
+
+/**
+ * A stand-in for a binding, so the local tier judges values rather than wiring.
+ *
+ * `EmailHostEnv` duck-types its bindings — it asserts the method the host calls, because these are host
+ * objects the runtime hands over and there is no class to compare against. That is what makes a stub
+ * possible here at all, and it is why the stub carries the methods rather than being an empty object: the
+ * schema would refuse `{}` and the report would fill with wiring faults doctor already states elsewhere.
+ */
+function stubBindings(): Record<string, unknown> {
+  const d1 = { prepare: () => undefined } as unknown as D1Database;
+  return {
+    DB: d1,
+    EMAIL_SUPPRESSIONS: d1,
+    SECRETS: d1,
+    SECRETS_ENCRYPTION_KEYS: "checked elsewhere",
+    EMAIL: { send: () => undefined },
+    EMAIL_SENDER: { create: () => undefined, get: () => undefined },
+    EMAIL_SCHEDULER: { create: () => undefined },
+  };
+}
+
+/** The domain half of an address, lowercased, or `null` where the address carries none usable. */
+function domainOf(address: string): string | null {
+  const at = address.lastIndexOf("@");
+  if (at < 0) return null;
+  const domain = address
+    .slice(at + 1)
+    .trim()
+    .toLowerCase();
+  return domain.includes(".") ? domain : null;
+}
+
+/** The origin of a URL, or `null` when it is not one. Compared origin-to-origin, never string-to-string. */
+function originOf(url: string): string | null {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The host's own parse of the values this composition would hand it.
+ *
+ * Run **once**, not once per environment, and reported with no environment named: `email({ … })` is one
+ * config object per Worker, so a `BASE_URL` that is not a URL is one edit however many environments a
+ * project declares. Three lines about one key is how a report stops being read.
+ */
+function localHostEnv(config: EmailSettingsInput): SettingsFinding[] {
+  const candidate = {
+    ...stubBindings(),
+    BASE_URL: config.baseUrl,
+    // Serialized exactly as `resolveEmailConfig` stamps it, so what is checked is what the host parses —
+    // a theme that resolves in TypeScript and does not survive a round trip through one JSON var is the
+    // failure this catches.
+    ...(config.theme ? { EMAIL_THEME: JSON.stringify(config.theme) } : {}),
+  };
+  return hostEnvFindings(checkHostEnv(emailHostEnv, candidate), null);
+}
+
+/**
+ * Whether the configured base URL is an origin this project actually answers on.
+ *
+ * `pithy email provision` stamps each host's `BASE_URL` from that environment's *resolved worker address*,
+ * so a deployed host is right by construction — but `email({ baseUrl })` is what `pithy dev` renders links
+ * against and what the repository states its intent with, and a value matching no declared origin is a
+ * link to a host nothing serves. Asked only when some environment declares one: a project before its first
+ * domain has nothing to compare against, and `Origins:` already reports that.
+ */
+function localBaseUrlOrigin(config: EmailSettingsInput, context: SettingsCheckContext): SettingsFinding[] {
+  const declared = context.environments
+    .map((environment) => (environment.origin === null ? null : originOf(environment.origin)))
+    .filter((origin): origin is string => origin !== null);
+  const configured = originOf(config.baseUrl);
+  if (declared.length === 0 || configured === null || declared.includes(configured)) return [];
+  return [
+    {
+      setting: "BASE_URL",
+      environment: null,
+      problem: `Links are built against ${configured}, and no environment this project declares answers on it.`,
+      action: `Set \`email({ baseUrl })\` to an origin this project serves: ${declared.join(", ")}.`,
+    },
+  ];
+}
+
+/** The address question, asked once: it is one config key, and one edit fixes every environment. */
+function localForAddress(config: EmailSettingsInput): SettingsFinding[] {
+  if (domainOf(config.fromAddress) !== null) return [];
+  return [
+    {
+      setting: "fromAddress",
+      environment: null,
+      problem: `${config.fromAddress} is not an address a sending domain can be read from.`,
+      action: "Set `email({ fromAddress })` to an address on a domain you have onboarded onto Email Service.",
+    },
+  ];
+}
+
+/** The last declared environment — the one a project-wide remedy is named for. */
+function lastEnvironment(context: SettingsCheckContext): string {
+  return context.environments.at(-1)?.name ?? "prod";
+}
+
+/** The account half: the zone, the suppression database, and the signing key. */
+async function accountFindings(
+  config: EmailSettingsInput,
+  context: SettingsAccountContext,
+): Promise<SettingsFinding[]> {
+  const findings: SettingsFinding[] = [];
+
+  const domain = domainOf(config.fromAddress);
+  // A domain the local tier already refused is not asked about again: it named the edit, and a second
+  // line about the same key would send the operator looking for a second problem.
+  if (domain !== null && !(await context.account.zone(domain))) {
+    findings.push({
+      setting: "fromAddress",
+      environment: null,
+      problem: `${domain} is not a zone on this Cloudflare account, so it cannot be onboarded onto Email Service.`,
+      action: `Add ${domain} to this Cloudflare account, then onboard it onto Email Service in the dashboard.`,
+    });
+  }
+
+  const suppressions = suppressionDatabaseName(context.project);
+  if (!(await context.account.d1Databases()).includes(suppressions)) {
+    findings.push({
+      setting: "EMAIL_SUPPRESSIONS",
+      environment: null,
+      problem: `No D1 database named ${suppressions} exists on this account.`,
+      // One database for the whole project, so the remedy is one run in any environment — named as the
+      // last declared one, which is the environment an operator is least likely to have skipped.
+      action: `Run \`pithy email provision --env ${lastEnvironment(context)}\`. Nothing is suppressed until it exists.`,
+    });
+  }
+
+  for (const environment of context.environments) {
+    // `dev` has no manager Worker to ask: a `d1` secret's value is sealed under a master key that never
+    // leaves the environment's manager, and local dev has none. Asking would be answered by a refusal,
+    // which the runner would report as an unchecked capability rather than as this clean pass.
+    if (environment.name === "dev") continue;
+    if (await context.account.secret({ name: EMAIL_LINK_SIGNING_KEY, environment: environment.name })) continue;
+    findings.push({
+      setting: EMAIL_LINK_SIGNING_KEY,
+      environment: environment.name,
+      problem: `The link-signing key has no value in ${environment.name}, so no tracking or unsubscribe link can be signed.`,
+      action: `Run \`pithy secrets provision --env ${environment.name}\`.`,
+    });
+  }
+
+  return findings;
+}
+
+/** Email's settings check, built from one composition's resolved config. Declared on the capability. */
+export function emailSettings(config: EmailSettingsInput): CapabilitySettings {
+  return {
+    local: (context) => [...localHostEnv(config), ...localForAddress(config), ...localBaseUrlOrigin(config, context)],
+    account: (context) => accountFindings(config, context),
+  };
+}

package/src/send/batchIdentity.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Batch identity — the one rule every dispatcher of a send Workflow keeps (pithy-sh/pithy#342).
+ *
+ * **A job's `batchId` names the send Workflow instance that is coming for it, and nothing else.** Null
+ * means no instance is. There is no third meaning, and in particular it is not a history of which batch
+ * touched the row last.
+ *
+ * It binds over every row in a status `runScheduler` queries — `scheduled`, `pending`, `sending` — which
+ * is every row the id can be read from. A terminal row (`sent`, `failed`, `suppressed`, `bounced`,
+ * `canceled`) keeps whatever it last carried, because no tick will ever look at it and clearing it
+ * would be a write bought for nobody. What that costs is exactly one obligation, and it is `retryJob`'s:
+ * the write that brings a terminal row back into the queried set must set this in the same statement.
+ *
+ * So the rule for a future writer is short. **If you move a job into `scheduled`, `pending` or
+ * `sending`, you own this column in that statement.** Three places do today.
+ *
+ * That is the whole basis of the scheduler's veto. `runScheduler` leaves a stale-looking row alone when
+ * the runtime says the instance it names is alive, so a row naming an instance that is *not* the one
+ * working it turns the veto into a lie in one of two directions:
+ *
+ * - It names a **dead** instance and a live one is working the row anyway — the tick re-drives, a second
+ *   Workflow renders and sends, and one person gets two copies.
+ * - It names a **live** instance that is not working the row — the tick holds a genuinely stranded job
+ *   for as long as some unrelated batch keeps running, and the mail does not go out.
+ *
+ * Three places set a job to a status the scheduler queries, so three places must uphold it: `enqueueEmail`
+ * (immediate dispatch), `retryJob` (an operator re-queueing a failure), and `runScheduler` itself (the
+ * claim). Each mints the id *before* the write that makes the row queryable and creates the instance
+ * under it afterwards, so the worst an interrupted dispatch can leave behind is a row naming an instance
+ * that does not exist — which the runtime disowns, which reads as dead, which is recovered. The failure
+ * mode of this design is a duplicate render that `runSend` short-circuits, never a duplicate send.
+ */
+
+/**
+ * Mint a batch id. A UUID, and deliberately nothing more.
+ *
+ * It becomes a Workflow instance id, so uniqueness is the only property it needs and the only one
+ * anything may read from it: a batch id is not a timestamp, not a shard key, and not sortable. It is
+ * here rather than inline at each dispatcher so that the three of them cannot drift into three id
+ * schemes, one of which collides and rejects a `create` nobody sees fail.
+ */
+export function mintBatchId(): string {
+  return crypto.randomUUID();
+}