@pithy-sh/cloudflare 0.1.0

package/src/test-utils/harness.ts

@@ -0,0 +1,413 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  AbortMultipartUploadCommand,
+  DeleteObjectCommand,
+  ListMultipartUploadsCommand,
+  ListObjectsV2Command,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { fitSegment, kebab, MAX_RESOURCE_NAME, RESERVED_TEST_PREFIX } from "@pithy-sh/core/src/naming/resource";
+import { CloudflareClients } from "../client/clients";
+import { CLOUDFLARE_ENV_KEYS, parseDevVars } from "../env/devVars";
+import { R2Credentials } from "../r2/r2Credentials";
+
+/**
+ * Shared scaffolding for the package's `*.integration.test.ts` live suites. Every live test does the
+ * same three things — find credentials, create a throwaway resource, and guarantee it is torn down —
+ * so that logic lives here once instead of being re-derived per manager. Generalized from the D1
+ * provisioner's first live test; see `README.md` § "Live integration tests" for the template.
+ */
+
+/**
+ * **This** package's root, whichever package's live suite is running — `@pithy-sh/storage` imports this
+ * harness, so its credentials come from `packages/cloudflare/.dev.vars` too, and a `.dev.vars` beside the
+ * importing package is read by nothing. See `README.md` § "Live integration tests".
+ *
+ * Nothing creates that file, and nothing in the CLI reads one any more — adopter credentials moved to
+ * the account-scoped `<config>/cloudflare.json` (#182), and this package cannot resolve that directory
+ * without a second implementation of where Pithy's config lives. So this stays a **maintainer-authored
+ * file for the live suites and nothing else**: no command writes it, no adopter has one, and it holds
+ * whatever account the person running `test:integration` wants the throwaway resources created in.
+ * Write it by hand, or export the keys — {@link loadIntegrationEnv} overlays `process.env` per key for
+ * anything the file does not set, which is how CI runs with no file at all.
+ */
+const PACKAGE_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+/**
+ * The live-suite credentials: this package's own `.dev.vars`, then `process.env` per key for anything it
+ * did not set. The `.dev.vars` half is why this is here rather than in `../env/devVars` — nothing outside
+ * a live test reads a `.dev.vars` for credentials now, and a shared function that still did would be an
+ * invitation to point a command back at the checkout.
+ *
+ * Exported for `fixtures.ts`, which resolves the whole fixture estate against the same pair. Two readers
+ * of two files is how a suite and its own report come to disagree about what this run has.
+ */
+export function loadIntegrationEnv(): Record<string, string> {
+  let vars: Record<string, string> = {};
+  try {
+    vars = parseDevVars(readFileSync(path.join(PACKAGE_ROOT, ".dev.vars"), "utf8"));
+  } catch {
+    // No file — rely on the environment overlay below.
+  }
+  for (const key of CLOUDFLARE_ENV_KEYS) {
+    const fromEnv = process.env[key];
+    if (!vars[key] && fromEnv) vars[key] = fromEnv;
+  }
+  return vars;
+}
+
+/** Cloudflare credentials for a live run, plus whether enough of them are present to run at all. */
+export interface IntegrationCreds {
+  /** The target account id (`CLOUDFLARE_ACCOUNT_ID`). Empty string when unset. */
+  accountId: string;
+  /** The scoped API token (`CLOUDFLARE_API_TOKEN`). Empty string when unset. */
+  apiToken: string;
+  /** The Secrets Store id (`SECRETS_STORE_ID`), for the secrets-store live test. Empty string when unset. */
+  secretsStoreId: string;
+  /** R2 S3 keys (from `R2_CREDENTIALS` JSON), for the R2 presigned-URL test. Null when unset. */
+  r2: R2Credentials | null;
+  /** True only when both an account id and a token are present — the gate for `describe.skipIf`. */
+  hasCreds: boolean;
+}
+
+/**
+ * Parse the `R2_CREDENTIALS` JSON blob through the canonical {@link R2Credentials} schema — the same
+ * object the R2 storage feature manages as a JSON payload, so the harness and the feature validate it
+ * identically. Returns null when unset (the R2 suite then skips); a set-but-malformed/invalid blob
+ * fails `.parse()` and throws, surfacing the misconfiguration loudly rather than silently skipping.
+ */
+export function parseR2Creds(raw: string | undefined): R2Credentials | null {
+  if (!raw) return null;
+  return R2Credentials.parse(JSON.parse(raw));
+}
+
+/**
+ * Load the live-CF credentials a `*.integration.test.ts` needs, reading the package `.dev.vars` and
+ * overlaying `process.env` (the loader's own fallback, so CI passes them as plain env vars). Gate the
+ * suite with `describe.skipIf(!loadIntegrationCreds().hasCreds)` so it skips cleanly with no creds.
+ */
+export function loadIntegrationCreds(): IntegrationCreds {
+  const vars = loadIntegrationEnv();
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  return {
+    accountId,
+    apiToken,
+    secretsStoreId: vars.SECRETS_STORE_ID ?? "",
+    r2: parseR2Creds(vars.R2_CREDENTIALS),
+    hasCreds: Boolean(accountId && apiToken),
+  };
+}
+
+/**
+ * The project name a live test provisions under, so that names composed by the *product's* provisioners —
+ * `<project>-<env>-<thing>`, where the project segment is verbatim and first — land inside the reservation
+ * too. A live test of `pithy provision --feature` cannot route through {@link uniqueName}: the names are the
+ * thing under test. Giving it a reserved project puts them in the namespace anyway.
+ *
+ * The reservation itself is {@link RESERVED_TEST_PREFIX}, in `@pithy-sh/core`. It lives beside the name
+ * composer because both sides of it are naming facts: this harness mints inside it, and `scaffoldProject`
+ * refuses to mint a project that would land in it. One literal, or the two drift apart.
+ */
+export const RESERVED_TEST_PROJECT = `${RESERVED_TEST_PREFIX}test`;
+
+/**
+ * The compatibility date every throwaway Worker a live suite uploads runs on.
+ *
+ * `createWorker` has no default any more (#396): a compatibility date is a behavior contract in
+ * somebody's account, so the caller names it. That makes every live suite a caller, and one place for
+ * them to read it from is the difference between one date and six.
+ *
+ * **It is stated rather than imported, and the reason is a wall rather than a preference.** The floor
+ * lives in `compatibility.ts` at the repository root, and this package's `rootDir` is `src` — a static
+ * import of a file above it is TS6059, the same wall `compatibilityDates.test.ts` records for
+ * `packages/cli`. So this is a fixture stating a date, which is the one shape that gate excludes on
+ * purpose. Keep it level with the floor when the floor moves.
+ */
+export const INTEGRATION_COMPATIBILITY_DATE = "2026-06-01";
+
+/** Deduplicates names minted within one test file; the random suffix covers the cross-file case. */
+let nameCounter = 0;
+
+/**
+ * Mint a collision-proof name for a throwaway live resource:
+ * `pithy-int-<label>-<timestamp>-<counter>-<rand>`.
+ *
+ * The caller supplies only the distinguishing part — {@link RESERVED_TEST_PREFIX} is composed on, never
+ * passed in. That is the point: when the prefix was a *default* a caller could override, a suite could
+ * silently create resources under a name the reaper does not recognize, which is exactly how orphans
+ * came to sit on a real account. A label that already carries the prefix is refused rather than doubled.
+ *
+ * The 6-char random suffix guarantees uniqueness across separate test files (Vitest isolates each file, so
+ * the counter only deduplicates within one); the timestamp is what {@link testResourceAge} reads, so every
+ * name this mints is reapable by construction. The label is kebabbed and fitted, so the result always
+ * stays inside R2's {@link MAX_RESOURCE_NAME} cap and the lowercase `a-z0-9-` charset every CF namespace
+ * accepts, whatever the caller passed.
+ */
+export function uniqueName(label: string): string {
+  const segment = kebab(label);
+  if (!segment) {
+    throw new ValidationError({
+      message: "A throwaway resource needs a label.",
+      action: "Pass a short label, e.g. uniqueName('kv').",
+      detail: `uniqueName received ${JSON.stringify(label)}, which kebabs to nothing.`,
+    });
+  }
+  if (segment.startsWith(RESERVED_TEST_PREFIX)) {
+    throw new ValidationError({
+      message: `A throwaway label must not repeat the reserved "${RESERVED_TEST_PREFIX}" prefix.`,
+      action: `Pass only the distinguishing part, e.g. uniqueName('${segment.slice(RESERVED_TEST_PREFIX.length) || "kv"}').`,
+      detail: `uniqueName composes ${RESERVED_TEST_PREFIX} itself; ${JSON.stringify(label)} would double it.`,
+    });
+  }
+
+  nameCounter += 1;
+  // `Math.random()` can produce a short base-36 string, and a name must never end on a hyphen.
+  const rand = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+  const suffix = `-${Date.now()}-${nameCounter}-${rand}`;
+  const budget = MAX_RESOURCE_NAME - RESERVED_TEST_PREFIX.length - suffix.length;
+  return `${RESERVED_TEST_PREFIX}${fitSegment(segment, budget)}${suffix}`;
+}
+
+/**
+ * Create a live resource, exercise it, and guarantee teardown — even if `exercise` throws. This is the
+ * spine of every live integration test: a failed assertion must never orphan a real Cloudflare resource.
+ * `create` runs outside the `try`, so a creation failure does not call `teardown` on something that was
+ * never created; once `create` resolves, `teardown` always runs in the `finally`. The exercise result is
+ * returned for the rare caller that wants it.
+ */
+export async function withThrowawayResource<R, T>(
+  create: () => Promise<R>,
+  exercise: (resource: R) => Promise<T>,
+  teardown: (resource: R) => Promise<void>,
+): Promise<T> {
+  const resource = await create();
+  try {
+    return await exercise(resource);
+  } finally {
+    await teardown(resource);
+  }
+}
+
+/**
+ * Create a live resource **at a name the caller already chose**, exercise it, and guarantee teardown —
+ * including when `create` itself rejects.
+ *
+ * {@link withThrowawayResource} runs `create` outside the `try` on purpose: for a kind whose id only
+ * exists once creation succeeds, tearing down a failed create would be tearing down nothing. But a whole
+ * family of Cloudflare calls are **named writes** — `putSecret(name, …)`, `createBucket(name)`,
+ * `createDatabase(name)`, `createWorker(name)` — where the address is the caller's own argument. There a
+ * rejection is ambiguous: the server may have accepted the write and failed on the way back, and the
+ * resource now exists under a name the test is still holding. `withThrowawayResource` walks away from it.
+ *
+ * This variant tears down on the **name**, and arms the teardown before `create` is ever called, so the
+ * ambiguous case cleans up. `teardown` must therefore tolerate a resource that was never created — every
+ * caller here passes an idempotent delete, and the reaper is the backstop if one is not.
+ */
+export async function withNamedResource<T>(
+  name: string,
+  create: (name: string) => Promise<unknown>,
+  exercise: (name: string) => Promise<T>,
+  teardown: (name: string) => Promise<void>,
+): Promise<T> {
+  try {
+    await create(name);
+    return await exercise(name);
+  } finally {
+    await teardown(name);
+  }
+}
+
+/**
+ * How old a resource must be before a reaper will remove it.
+ *
+ * **Twelve hours, and the size is the safety argument.** Reaping is a race with any suite that is still
+ * running: a resource deleted mid-flight surfaces as an unexplained 404 in a test that was passing, which
+ * is a far worse failure than debris. Cloudflare offers no way to mark a D1, KV namespace, bucket, or
+ * index as owned by a live process — no lease, no tag our client can set on every kind — so the only
+ * defense available is a window nothing plausible can cross.
+ *
+ * A single live test is capped at 120s and a hook at 120s (`vitest.integration.config.ts`); a whole
+ * package's suite is minutes, and every package's suites together are well under an hour even when
+ * Vectorize is settling. Twelve hours is two orders of magnitude past that, and still short enough that
+ * debris never survives a day. The cost of the wider window is a handful of orphans lingering longer;
+ * the cost of the narrower one is a green suite turned red by its own housekeeping.
+ */
+export const DEFAULT_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
+
+/**
+ * The ms-epoch {@link uniqueName} embedded, or `null` if this is not one of our names.
+ *
+ * `uniqueName` composes `pithy-int-<label>-<epoch>-<counter>-<rand>`, so the timestamp is the third
+ * segment from the end. Anything that does not match that shape returns `null` and is therefore never
+ * reaped — including a name inside the reservation that some *other* generator produced, such as a
+ * feature resource provisioned under {@link RESERVED_TEST_PROJECT}. Conservative on purpose: failing to
+ * clean up costs pennies, deleting someone's data does not.
+ */
+export function testResourceAge(name: string, now: number): number | null {
+  if (!name.startsWith(RESERVED_TEST_PREFIX)) return null;
+  const segments = name.split("-");
+  if (segments.length < 3) return null;
+  const stamp = Number(segments[segments.length - 3]);
+  if (!Number.isInteger(stamp) || stamp <= 0 || stamp > now) return null;
+  return now - stamp;
+}
+
+/**
+ * Which of these names are stale test debris — ours, and old enough that no running suite owns them.
+ *
+ * Pure, so the age arithmetic is unit-tested without touching Cloudflare.
+ */
+export function staleTestResourceNames(
+  names: readonly string[],
+  options: { now?: number; staleAfterMs?: number } = {},
+): string[] {
+  const now = options.now ?? Date.now();
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  return names.filter((name) => {
+    const age = testResourceAge(name, now);
+    return age !== null && age >= staleAfterMs;
+  });
+}
+
+/** One reapable resource kind: what it is called, how to list it, and how to remove one. */
+export interface ReapableKind {
+  /** Human label for the reap log, e.g. "Vectorize index". */
+  label: string;
+  /** Every resource name of this kind currently in the account. */
+  list: () => Promise<string[]>;
+  /** Remove one by name. Must be idempotent — another runner may have reaped it first. */
+  remove: (name: string) => Promise<void>;
+}
+
+/**
+ * Remove stale throwaway resources of one kind, and report what went.
+ *
+ * `withThrowawayResource` guarantees teardown only while the process lives. A run killed by a test
+ * timeout, a Ctrl-C, or a crash orphans whatever it had created — which is exactly how two Vectorize
+ * indexes came to sit on a real account for a month. Calling this in a suite's `beforeAll` makes each
+ * run clean up after the last one, so the failure mode self-heals instead of accumulating.
+ *
+ * Never throws: a reaper that fails must not fail the suite it is trying to help. Failures are reported
+ * in the returned list of what could not be removed.
+ */
+export async function reapStaleTestResources(
+  kind: ReapableKind,
+  options: { now?: number; staleAfterMs?: number } = {},
+): Promise<{ reaped: string[]; failed: string[] }> {
+  const reaped: string[] = [];
+  const failed: string[] = [];
+  let names: string[];
+  try {
+    names = await kind.list();
+  } catch {
+    return { reaped, failed };
+  }
+
+  for (const name of staleTestResourceNames(names, options)) {
+    try {
+      await kind.remove(name);
+      reaped.push(name);
+    } catch {
+      failed.push(name);
+    }
+  }
+
+  if (reaped.length > 0) console.warn(`reaped ${reaped.length} stale ${kind.label}(s): ${reaped.join(", ")}`);
+  if (failed.length > 0) console.warn(`could not reap ${failed.length} stale ${kind.label}(s): ${failed.join(", ")}`);
+  return { reaped, failed };
+}
+
+/**
+ * An S3 client for the account's R2, built from the harness's own key pair.
+ *
+ * **R2 is the one kind the API token cannot reap.** Cloudflare refuses to delete a non-empty bucket, and
+ * emptying one is an S3-protocol operation — `ListObjectsV2`, `DeleteObject`, `AbortMultipartUpload` —
+ * that the REST API does not offer and a scoped API token cannot authenticate. So the harness holds the
+ * S3 credentials itself: {@link IntegrationCreds.r2}, parsed from `R2_CREDENTIALS`, is what makes a
+ * throwaway bucket reclaimable at all.
+ *
+ * Raw S3 rather than `CloudflareR2Manager` on purpose. This is teardown, and teardown must not depend on
+ * the code under test: if `emptyBucket` is the thing that broke, the bucket still has to come back empty
+ * or a failing test leaks a real resource instead of reporting a bug.
+ */
+function testS3(creds: IntegrationCreds): S3Client {
+  if (!creds.r2) {
+    throw new ValidationError({
+      message: "Emptying an R2 bucket needs the S3 key pair.",
+      action: "Set R2_CREDENTIALS in .dev.vars, or gate the suite on `creds.r2`.",
+      detail: "R2 refuses to delete a non-empty bucket, and draining one is an S3 operation, not a REST one.",
+    });
+  }
+  return new S3Client({
+    region: "auto",
+    endpoint: `https://${creds.accountId}.r2.cloudflarestorage.com`,
+    credentials: { accessKeyId: creds.r2.accessKeyId, secretAccessKey: creds.r2.secretAccessKey },
+  });
+}
+
+/**
+ * Empty a throwaway bucket so R2 will delete it.
+ *
+ * Two things hold a bucket against deletion: stored objects, and the parts of a multipart upload that was
+ * never completed or aborted — precisely what a test that failed mid-upload leaves behind. Both are
+ * cleared, dangling uploads first. Every page is drained, so a bucket with more than a thousand keys is
+ * emptied rather than half-emptied.
+ *
+ * Throws when the S3 key pair is absent: a bucket that cannot be emptied cannot be deleted, and silence
+ * there is how debris becomes permanent.
+ */
+export async function emptyTestBucket(creds: IntegrationCreds, bucketName: string): Promise<void> {
+  const s3 = testS3(creds);
+  const uploads = await s3.send(new ListMultipartUploadsCommand({ Bucket: bucketName }));
+  for (const upload of uploads.Uploads ?? []) {
+    if (!upload.Key || !upload.UploadId) continue;
+    await s3.send(new AbortMultipartUploadCommand({ Bucket: bucketName, Key: upload.Key, UploadId: upload.UploadId }));
+  }
+
+  let token: string | undefined;
+  do {
+    const page = await s3.send(new ListObjectsV2Command({ Bucket: bucketName, ContinuationToken: token }));
+    for (const entry of page.Contents ?? []) {
+      if (entry.Key) await s3.send(new DeleteObjectCommand({ Bucket: bucketName, Key: entry.Key }));
+    }
+    token = page.IsTruncated ? page.NextContinuationToken : undefined;
+  } while (token);
+}
+
+/**
+ * Reclaim stale throwaway R2 buckets — the one kind that needs more than an API token, so it lives here
+ * once instead of being re-derived by every suite that makes a bucket.
+ *
+ * Without `R2_CREDENTIALS` this reaps nothing and says so loudly rather than failing quietly: the buckets
+ * are still there, still cost money, and the only fix is the key pair. Never throws — a reaper must not
+ * fail the suite it is trying to help.
+ */
+export async function reapStaleTestBuckets(
+  creds: IntegrationCreds,
+  options: { now?: number; staleAfterMs?: number } = {},
+): Promise<{ reaped: string[]; failed: string[] }> {
+  if (!creds.r2) {
+    console.warn("no R2_CREDENTIALS: stale pithy-int- buckets cannot be emptied, so none were reaped.");
+    return { reaped: [], failed: [] };
+  }
+
+  const provisioner = new CloudflareClients({ accountId: creds.accountId, apiToken: creds.apiToken }).r2Provisioner();
+  return reapStaleTestResources(
+    {
+      label: "R2 bucket",
+      list: async () => (await provisioner.listBuckets()).map((bucket) => bucket.name),
+      remove: async (name) => {
+        await emptyTestBucket(creds, name);
+        await provisioner.deleteBucket(name);
+      },
+    },
+    options,
+  );
+}

package/src/test-utils/inboundRecorder.ts

@@ -0,0 +1,189 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { CloudflareInvalidResponseError, CloudflareRequestError } from "../client/errors";
+import type { CloudflareWorkersManager } from "../workers/workersManager";
+import type { IntegrationCreds } from "./harness";
+
+/**
+ * A throwaway Worker that records what its `email()` handler was handed, and the reader that fetches
+ * the record back out.
+ *
+ * ## Why a Worker has to exist at all
+ *
+ * An Email Routing rule cannot point at a Worker that is not there. Cloudflare rejects the rule with
+ * `2016 Workers Script Info not found` at creation time, so a live test of `ensureWorkerRoute` has to
+ * deploy a real script before it can create a real rule. That fact alone forces this file; everything
+ * else here is what the script may as well do once it is running.
+ *
+ * ## Why the record goes through KV
+ *
+ * There is no inbox. The fixture zone's catch-all drops and it has zero verified destination
+ * addresses, so nothing this suite sends can be read from a mailbox — and a test that waits for one
+ * waits forever. The Worker is the destination, so the Worker has to be the witness: it writes what it
+ * received to a KV namespace the test created, and the test reads it back over the REST API.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not classify, suppress, or parse MIME. Everything `@pithy-sh/email` actually does with an
+ * inbound message is unit-tested against real D1 in the Workers pool, where a hostile message can be
+ * constructed exactly rather than mailed and hoped for. What only a live delivery can answer is what
+ * Cloudflare *hands* the handler — which headers survive, which Cloudflare adds, and whether a
+ * sender's own headers arrive intact. So the recorder records, and asserts nothing.
+ */
+
+/** The KV binding the recorder writes through. */
+export const INBOUND_RECORDER_BINDING = "OBSERVED";
+
+/** The header a sender stamps to address its record. One send, one key, so parallel runs cannot collide. */
+export const INBOUND_NONCE_HEADER = "X-Pithy-Probe";
+
+/**
+ * How much of the raw message is kept.
+ *
+ * A record is read back into a test's failure output, and a whole message is pages of base64. 16 KiB
+ * covers the header block several times over, which is the part every question in #47 is about.
+ */
+const RAW_CAP = 16_384;
+
+/** How long a record lives in KV. An hour outlives any run and reclaims itself if a teardown is missed. */
+const RECORD_TTL_SECONDS = 3600;
+
+/**
+ * The recorder's source, as a module string.
+ *
+ * Kept verbatim here rather than built from a template because it is uploaded as-is and read by whoever
+ * is debugging a delivery that did not arrive. It writes **once**, under the nonce it finds in the raw
+ * message, and it must never throw: a throw inside `email()` is a delivery failure Cloudflare retries,
+ * which turns one test message into several.
+ */
+export const INBOUND_RECORDER_MODULE = `
+const NONCE = /^${INBOUND_NONCE_HEADER}:[ \\t]*(\\S+)[ \\t]*$/im;
+const AUTH_RESULTS = /^Authentication-Results:[ \\t]*([\\s\\S]*?)(?=\\r?\\n[^ \\t])/gim;
+
+/** Header names in the raw block, in order, lowercased. Duplicates kept — two DKIM signatures are two facts. */
+function rawHeaderNames(raw) {
+  const block = raw.split(/\\r?\\n\\r?\\n/)[0] ?? "";
+  return block
+    .split(/\\r?\\n/)
+    .filter((line) => /^[A-Za-z0-9-]+:/.test(line))
+    .map((line) => line.slice(0, line.indexOf(":")).toLowerCase());
+}
+
+export default {
+  async email(message, env) {
+    let record;
+    let nonce = "unkeyed";
+    try {
+      const raw = await new Response(message.raw).text();
+      nonce = NONCE.exec(raw)?.[1] ?? "unkeyed";
+      record = {
+        envelopeFrom: message.from,
+        envelopeTo: message.to,
+        rawSize: message.rawSize,
+        seen: [...message.headers.keys()].map((name) => name.toLowerCase()).sort(),
+        rawHeaderNames: rawHeaderNames(raw),
+        authenticationResults: [...raw.matchAll(AUTH_RESULTS)].map((match) => match[1].trim()),
+        raw: raw.slice(0, ${RAW_CAP}),
+      };
+    } catch (error) {
+      record = { failure: String(error) };
+    }
+    await env.${INBOUND_RECORDER_BINDING}.put(nonce, JSON.stringify(record), { expirationTtl: ${RECORD_TTL_SECONDS} });
+  },
+};
+`;
+
+/**
+ * What the recorder saw — validated on the way back in, because a KV read is a boundary like any other.
+ *
+ * The Worker that wrote it is ours, which is exactly the argument that has let every unvalidated
+ * internal read through. A truncated write or a stale record from an older recorder deserves a Zod
+ * failure naming the field, not a `TypeError` three assertions later.
+ */
+export const ObservedInbound = z
+  .object({
+    envelopeFrom: z.string().describe("The SMTP envelope sender, as `message.from` reported it."),
+    envelopeTo: z.string().describe("The SMTP envelope recipient, as `message.to` reported it."),
+    rawSize: z.number().describe("The message size in bytes, as `message.rawSize` reported it."),
+    seen: z
+      .array(z.string())
+      .describe("Header names on `message.headers`, lowercased and sorted — the surface workerd#6740 is about."),
+    rawHeaderNames: z
+      .array(z.string())
+      .describe("Header names in the raw MIME block, lowercased, in wire order, duplicates kept."),
+    authenticationResults: z
+      .array(z.string())
+      .describe("Every `Authentication-Results` value in the raw block, in wire order: the topmost is the receiver's."),
+    raw: z.string().describe("The delivered message, truncated to the first 16 KiB."),
+  })
+  .describe("One inbound message as the Worker's `email()` handler received it.");
+
+/** What the recorder saw. */
+export type ObservedInbound = z.output<typeof ObservedInbound>;
+
+/** A trivial module Worker: enough for an Email Routing rule to be allowed to point at it. */
+export const PLACEHOLDER_INBOUND_MODULE = "export default { async email() {} };\n";
+
+/** The module filename every throwaway Worker here is uploaded under. */
+export const INBOUND_MODULE_NAME = "worker.mjs";
+
+/**
+ * Deploy the recorder at `scriptName`, bound to the KV namespace records are written to.
+ *
+ * Uploaded through `CloudflareWorkersManager.createWorker` like anything else. It briefly was not:
+ * #373 was a manager that could not upload a module to the live API at all, and this file carried a
+ * hand-rolled `fetch` around it. The manager is the path again — a helper that exists because the
+ * product is broken is the thing people copy.
+ */
+export async function deployInboundRecorder(options: {
+  workers: CloudflareWorkersManager;
+  scriptName: string;
+  namespaceId: string;
+  /** The date this throwaway Worker runs on. Named by the suite, because #396 left no default to inherit. */
+  compatibilityDate: string;
+}): Promise<void> {
+  const { workers, scriptName, namespaceId, compatibilityDate } = options;
+  await workers.createWorker(
+    scriptName,
+    compatibilityDate,
+    { bindings: [{ type: "kv_namespace", name: INBOUND_RECORDER_BINDING, namespace_id: namespaceId }] },
+    { name: INBOUND_MODULE_NAME, body: INBOUND_RECORDER_MODULE },
+  );
+}
+
+/**
+ * The record for one nonce, or null while nothing has arrived.
+ *
+ * Null rather than a throw for the missing case, because "not yet" is the normal state of a mail
+ * delivery: the caller polls. A 404 from KV is that state; anything else is a real failure and throws.
+ */
+export async function readObservedInbound(options: {
+  creds: IntegrationCreds;
+  namespaceId: string;
+  nonce: string;
+}): Promise<ObservedInbound | null> {
+  const { creds, namespaceId, nonce } = options;
+  const url = `https://api.cloudflare.com/client/v4/accounts/${creds.accountId}/storage/kv/namespaces/${namespaceId}/values/${encodeURIComponent(nonce)}`;
+  const response = await fetch(url, { headers: { Authorization: `Bearer ${creds.apiToken}` } });
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new CloudflareRequestError({
+      message: "Could not read the recorded inbound message.",
+      action: "Check the token carries Workers KV Storage: Edit on this account.",
+      detail: `KV read for the inbound record returned ${response.status}.`,
+    });
+  }
+
+  const body: unknown = JSON.parse(await response.text());
+  // The recorder writes `{ failure }` rather than throwing, so a handler that broke says so here
+  // instead of arriving as a Zod complaint about seven missing fields.
+  if (typeof body === "object" && body !== null && "failure" in body) {
+    throw new CloudflareInvalidResponseError({
+      message: "The inbound recorder could not read the message it was handed.",
+      detail: `The recorder Worker recorded a failure: ${String((body as { failure: unknown }).failure)}`,
+    });
+  }
+  return ObservedInbound.parse(body);
+}

package/src/test-utils/integrationSetup.ts

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { fixtureValue, reportFixtureEstate, resolveFixture } from "./fixtures";
+import { loadIntegrationCreds } from "./harness";
+import { reapAllStaleTestResources } from "./reap";
+
+/**
+ * The Vitest `globalSetup` every `vitest.integration.config.ts` points at — one fixture report and one
+ * debris sweep per integration run, before a single suite is collected.
+ *
+ * **A `globalSetup` is the only place either can correctly live.** Reaping used to happen in a suite's
+ * `beforeAll`, and Vitest runs no hooks inside a `describe.skipIf(true)` — so each reaper was gated on
+ * exactly the credential whose absence lets debris pile up, and a package with no live suite of its own
+ * reaped nothing however much it created. `globalSetup` runs before collection, so no suite's gate can
+ * switch it off, and it runs once per project rather than once per file.
+ *
+ * The fixture report is the same argument about a different thing. A suite that skips for want of a
+ * Turnstile widget prints "skipped" and nothing else, and the one place that can say *which* fixture and
+ * *where to make it* is a place no suite's gate reaches. So it runs first, and it runs **before the
+ * credentials check** — a contributor with no account is exactly who needs to be told why the run went
+ * quiet, and gating the explanation on the thing being explained is how it goes silent for them.
+ *
+ * Never throws. Housekeeping that fails the run it was meant to help is worse than the debris: a missing
+ * or unprivileged token must skip the sweep and let the suites make their own skip decision, exactly as
+ * they did before.
+ */
+export default async function setup(): Promise<void> {
+  reportFixtureEstate();
+
+  const creds = loadIntegrationCreds();
+  if (!creds.hasCreds) return;
+
+  // The one zone-scoped kind. The fixture is the only thing that may name a zone this run is allowed to
+  // edit routing on; without it, that kind reports itself skipped rather than guessing.
+  const routing = resolveFixture("email-routing");
+  const emailRoutingZoneId = routing.ready ? fixtureValue("email-routing", "EMAIL_ROUTING_ZONE_ID") : undefined;
+
+  try {
+    await reapAllStaleTestResources(creds, { emailRoutingZoneId });
+  } catch (error) {
+    // Deliberately swallowed, and reported. The sweep is a courtesy to the next run; a run that cannot
+    // sweep is still a run worth having.
+    console.warn(`stale test resources could not be swept: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}