cursedbelt-server 4.9.0 → 4.11.0

package/src/publicSurface.spec.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'bun:test';
+import { run } from '../scripts/publicSurface';
+
+/**
+ * The public-surface ratchet, wired into `bun run verify` at its cheapest correct
+ * home: `verify` ends in `bun test src`, so this needs no new script and cannot be a
+ * script somebody forgot to chain.
+ *
+ * WHY it exists, WHAT a symbol count includes and excludes, why the dependency list
+ * and the used-vs-exported ratio are deliberately NOT computed here, and what
+ * `--prune` may and may not do are all in the header of `scripts/publicSurface.ts` —
+ * one check, one baseline (`publicSurface.baseline`), one place that explains itself.
+ * This file is only the wiring.
+ *
+ * 🔴 Verified failing, 2026-09-19, before it was trusted — every branch, not just the
+ * easy one. Each probe was applied, observed, and removed again:
+ *
+ *   · `export const ratchetProbe = 1` appended to `src/server/errors.ts`
+ *       → this file's "ceiling" test red — `3 pass, 1 fail`, "exports no more symbols per
+ *         subpath than the baseline allows" — and the CLI:
+ *         "1 subpath(s) that gained exported symbols · ./errors — baseline allows 14,
+ *          exports 15 now"
+ *   · the same line appended to `src/server/guard/revocationStore.ts`, which is where the
+ *     transitive `export *` walk is actually visible: `./guard/revocations` points at that
+ *     file and `./guard`'s barrel does `export * from './revocationStore'`
+ *       → "2 subpath(s) that gained exported symbols · ./guard — baseline allows 25,
+ *          exports 26 now · ./guard/revocations — baseline allows 7, exports 8 now".
+ *         🔴 TWO from one line, which is the walk the header promises, seen working. Note
+ *         which probe does NOT do this: `.` is a barrel of 219 NAMED re-exports, so a new
+ *         symbol in `errors.ts` does not reach it. A probe chosen in the wrong module
+ *         would have "proved" the transitive walk by never exercising it.
+ *   · a `"./probe"` subpath added to `package.json` `exports`, pointed at
+ *     `./src/server/errors.ts`
+ *       → "1 export subpath(s) the baseline does not know · ./probe — NEW subpath,
+ *          14 exported symbol(s)"
+ *   · `VALIDATION_STATUS` removed from the re-export list in `src/server/errors.ts`, no prune
+ *       → "1 baseline entr(y|ies) that no longer match `exports` · ./errors — baseline
+ *          says 14, exports 13"
+ *   · a `5  ./gone` line added to the baseline by hand
+ *       → same failure, "./gone — baseline says 5, the subpath is gone". An entry
+ *         matching nothing is the half that stops a deleted module leaving an allowance.
+ *   · `--prune` run against the grown surface
+ *       → "refuses while the surface has GROWN — it may only lower the baseline", exit 1
+ *   · `--prune` run against the shrunk surface
+ *       → "pruned to 34 subpath(s), 0 removed, 990 symbols", exit 0, and `14  ./errors`
+ *         became `13  ./errors` in the file — the burn-down path
+ *   · `--seed` run over the seeded baseline
+ *       → "refuses: … already records 34 subpath(s)", exit 1
+ *
+ * Every probe was reverted with `git checkout -- <path>`; the tree afterwards held only
+ * this file, `scripts/publicSurface.ts` and `publicSurface.baseline`.
+ *
+ * A ratchet nobody has seen red is a ratchet nobody knows is wired up.
+ */
+const result = await run();
+
+describe('public surface', () => {
+	it('has measured a real surface', () => {
+		// Guards the three assertions below: if `exports` were ever read as empty, every
+		// one of them passes vacuously and the ratchet quietly dies.
+		// 🔴 20, not 34: a vacuity guard set at the real surface fails for the one reason
+		// a vacuity guard must never fail — the surface being healthy and simply smaller.
+		expect(result.surface.counts.size).toBeGreaterThan(20);
+	});
+
+	it('publishes no export subpath the baseline does not know', () => {
+		expect(
+			result.fresh,
+			`new public subpath(s) — a permanent promise. Add the line to publicSurface.baseline and say why:\n  ${result.fresh.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('exports no more symbols per subpath than the baseline allows', () => {
+		expect(
+			result.grown,
+			`a baseline entry is a ceiling, not an amnesty:\n  ${result.grown.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('has no baseline entry that outlived the surface it recorded', () => {
+		// The half that makes it a RATCHET: a deleted module may not leave an allowance
+		// behind for the next one to grow into.
+		expect(
+			result.stale,
+			`surface came off and the ratchet was not tightened — run \`bun scripts/publicSurface.ts --prune\`:\n  ${result.stale.join('\n  ')}`,
+		).toEqual([]);
+	});
+});

package/src/server/bench/cpuBudget.spec.ts

@@ -10,7 +10,7 @@ import {
   workerCpuClock,
 } from './cpuClock';
 import { createCpuRecorder } from './recorder';
-import { runCpuBench } from './runBench';
+import { BENCH_ORIGIN, runCpuBench } from './runBench';
 
 /**
  * 🔴 **The assertion must fire in BOTH directions or it is decoration.** A gate that can
@@ -306,6 +306,196 @@ describe('the bench runner', () => {
   });
 });
 
+/**
+ * 🔴 **A destructive route benched without a fixture rebuild reports a number for the wrong
+ * reason**, and `expectStatus` cannot see it: the second purge legitimately answers 200 with
+ * `{ deleted: 0 }`. One call runs against a populated library and the next twenty-nine
+ * against an empty one, so the p99 describes the empty case and the budget it satisfies
+ * means nothing. The first block below IS that hole, measured; `beforeEach` is what closes
+ * it; the last two are the ways closing it could itself become a lie.
+ *
+ * Filed 2026-09-19 by the `collections` port — the first app to mount this harness — which
+ * had to leave `POST /api/duplicates/rescan` and `POST /api/recycle/purge`, the only two
+ * routes in it whose cost is O(catalogue), declared but unbenched for exactly this reason.
+ */
+describe('a destructive case — the fixture rebuild between iterations', () => {
+  /** ~4 CPU-ms per item held, ~0 CPU-ms when the library is empty. */
+  const PURGE_ITEM_MS = 4;
+  const PURGE_ITEMS = 3;
+  const POPULATED_MS = PURGE_ITEM_MS * PURGE_ITEMS;
+
+  /** A route whose cost is O(library) and which EMPTIES the library — a purge, in miniature. */
+  function buildDestructiveApp() {
+    const recorder = createCpuRecorder({
+      clock: processCpuClock(),
+      config: { routes: { 'POST /api/purge': 60 } },
+    });
+    const app = new Hono();
+    app.use('*', cpuBudget({ recorder }));
+    let library: string[] = [];
+    /** How many items each call actually found to purge — the fixture's state, per iteration. */
+    const purged: number[] = [];
+    app.post('/api/purge', (c) => {
+      let acc = 0;
+      for (const item of library) acc += burnCpu(PURGE_ITEM_MS) + item.length;
+      purged.push(library.length);
+      library = [];
+      return c.json({ deleted: purged[purged.length - 1], acc });
+    });
+    const seed = () => {
+      library = Array.from({ length: PURGE_ITEMS }, (_, i) => `item-${i}`);
+    };
+    return { app, recorder, seed, purged };
+  }
+
+  it('WITHOUT the hook, measures an empty library from the second call on — the hole itself', async () => {
+    const d = buildDestructiveApp();
+    d.seed();
+    // warmup 0 so the one populated call is a measured sample rather than a discarded one —
+    // otherwise the trap would be invisible here for a second, different reason.
+    const report = await runCpuBench({
+      app: d.app,
+      recorder: d.recorder,
+      cases: [{ method: 'POST', path: '/api/purge' }],
+      iterations: 100,
+      warmup: 0,
+    });
+
+    // One real purge, ninety-nine against nothing.
+    expect(d.purged[0]).toBe(PURGE_ITEMS);
+    expect(d.purged.slice(1).every((n) => n === 0)).toBe(true);
+
+    const row = report.routes[0];
+    expect(row.max).toBeGreaterThan(POPULATED_MS * 0.5); // the route really does cost this
+    expect(row.p99).toBeLessThan(2); // …and the number the budget is read off says it does not
+    expect(assertCpuBudgets(report)).toEqual([]); // green, and meaningless. That is the bug.
+  });
+
+  it('WITH the hook, measures the populated library on every single iteration', async () => {
+    const d = buildDestructiveApp();
+    const seen: number[] = [];
+    const report = await runCpuBench({
+      app: d.app,
+      recorder: d.recorder,
+      cases: [
+        {
+          method: 'POST',
+          path: '/api/purge',
+          beforeEach: (c, iteration) => {
+            expect(c.path).toBe('/api/purge');
+            seen.push(iteration);
+            d.seed();
+          },
+        },
+      ],
+      iterations: 20,
+      warmup: 2,
+    });
+
+    // 🔴 EVERY call found a full library, warm-up included — not just the first.
+    expect(d.purged).toHaveLength(22);
+    expect(d.purged.every((n) => n === PURGE_ITEMS)).toBe(true);
+    // The iteration counter is 0-based and monotonic across both passes, so a hook that
+    // seeds ids from it cannot collide between the warm-up and the measured run.
+    expect(seen).toEqual(Array.from({ length: 22 }, (_, i) => i));
+
+    const row = report.routes[0];
+    expect(row.samples).toBe(20);
+    // The p50 — not just the max — now carries the real cost. Before the hook it was ~0.
+    expect(row.p50).toBeGreaterThan(POPULATED_MS * 0.5);
+    expect(row.p99).toBeGreaterThan(POPULATED_MS * 0.5);
+  });
+
+  it('is PER CASE — a cheap read case beside a destructive one pays nothing for it', async () => {
+    const d = buildDestructiveApp();
+    d.app.get('/api/cheap', (c) => c.json({ ok: true }));
+    let rebuilds = 0;
+    const report = await runCpuBench({
+      app: d.app,
+      recorder: d.recorder,
+      cases: [
+        { path: '/api/cheap' },
+        {
+          method: 'POST',
+          path: '/api/purge',
+          beforeEach: () => {
+            rebuilds += 1;
+            d.seed();
+          },
+        },
+      ],
+      iterations: 20,
+      warmup: 1,
+    });
+
+    // 21 for the destructive case and not one for the read — the read case never called it.
+    expect(rebuilds).toBe(21);
+    expect(d.purged).toHaveLength(21);
+    const cheap = report.routes.find((r) => r.route === '/api/cheap');
+    const purge = report.routes.find((r) => r.route === '/api/purge');
+    expect(cheap?.p99).toBeLessThan(2);
+    expect(purge?.p99).toBeGreaterThan(POPULATED_MS * 0.5);
+  });
+
+  /*
+   * 🔴 The hook's own CPU must not land in the histogram. It is excluded by ORDERING — the
+   * recorder is written through by the middleware inside `app.fetch`, and the hook runs
+   * outside it — and ordering is an accident, so it is asserted here rather than relied on.
+   * A fixture rebuild that cost 200 ms and got attributed to the route would make this
+   * feature a worse lie than the hole it closes.
+   */
+  it("🔴 does NOT record the hook's own CPU, however expensive the rebuild is", async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5 } });
+    let rebuilds = 0;
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [
+        {
+          path: '/api/cheap',
+          beforeEach: () => {
+            rebuilds += 1;
+            burnCpu(SLOW_MS); // 30 CPU-ms of rebuild, ~3× the default budget, every iteration
+          },
+        },
+      ],
+      iterations: 20,
+      warmup: 2,
+    });
+
+    expect(rebuilds).toBe(22); // 22 × 30 CPU-ms was genuinely burned during this run…
+    const row = report.routes[0];
+    expect(row.samples).toBe(20);
+    // …and none of it is in these numbers. Even the MAX stays far under one rebuild.
+    expect(row.max).toBeLessThan(SLOW_MS / 3);
+    expect(row.p99).toBeLessThan(5);
+    expect(assertCpuBudgets(report)).toEqual([]);
+  });
+
+  it('REFUSES a hook that rebuilds the fixture through the app under bench', async () => {
+    // The obvious way to re-seed a library is to drive the app that has the routes. Those
+    // requests go through `cpuBudget()` like any other, so the rebuild would land in the
+    // report as real samples on real routes — the same lie, arriving from the other side.
+    const { app, recorder } = buildApp({});
+    await expect(
+      runCpuBench({
+        app,
+        recorder,
+        cases: [
+          {
+            path: '/api/cheap',
+            beforeEach: async () => {
+              await app.request(`${BENCH_ORIGIN}/api/cheap`);
+            },
+          },
+        ],
+        iterations: 5,
+        warmup: 0,
+      }),
+    ).rejects.toThrow(/beforeEach drove 1 request\(s\) through the app under bench/);
+  });
+});
+
 /**
  * 🔴 **The third direction: a gate that CANNOT go red.**
  *

package/src/server/bench/cpuClock.spec.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { cpuBudget } from './cpuBudget';
+import { processCpuClock } from './cpuClock';
+
+/**
+ * 🔴 **The runtime this file exists for is the one `bun test` is not.**
+ *
+ * Measured 2026-09-19 on the first real deploy of `apps/collections`:
+ * `https://collections.curtwphillips.workers.dev/healthz` answered
+ * `500 Internal Server Error` on every path, with 843 green tests behind it. Under
+ * `nodejs_compat`, workerd PROVIDES `process.cpuUsage` and throws when it is called —
+ *
+ * ```
+ * Error [ERR_METHOD_NOT_IMPLEMENTED]: The process.cpuUsage method is not implemented
+ *     at process.cpuUsage (node-internal:public_process:235:11)
+ *     at Object.start (index.js:2772:30)     <- cpuBudget's middleware
+ * ```
+ *
+ * — so the old `typeof process.cpuUsage === 'function'` probe said *available*, and
+ * `cpuBudget()`, which is mounted FIRST by design, threw in front of the whole app.
+ *
+ * Every case below stubs a THROWING method, not a missing one; a missing one was always
+ * handled and was never the bug.
+ *
+ * 🔴 Proven red, 2026-09-19, by putting the `typeof` probe back: **`2 pass, 4 fail`**. The
+ * second case reproduced the outage exactly, stack and all —
+ *
+ * ```
+ * error: The process.cpuUsage method is not implemented  code: "ERR_METHOD_NOT_IMPLEMENTED"
+ *     at start (src/server/bench/cpuClock.ts:59:30)
+ *     at <anonymous> (src/server/bench/cpuBudget.ts:54:32)
+ *   expect(res.status).toBe(200)   Expected: 200   Received: 500
+ * ```
+ *
+ * The two that passed against the old code are the two that must: `(absent)`, which the
+ * `typeof` probe did answer correctly, and the real-runtime direction.
+ */
+
+const REAL_CPU_USAGE = process.cpuUsage;
+
+/** Replace `process.cpuUsage` for one test. Restored by the `afterEach` below, always. */
+function stubCpuUsage(fn: unknown): void {
+  (process as unknown as { cpuUsage: unknown }).cpuUsage = fn;
+}
+
+/** workerd's shape: present, callable, and it throws. */
+function methodNotImplemented(): never {
+  const err = new Error('The process.cpuUsage method is not implemented');
+  (err as Error & { code?: string }).code = 'ERR_METHOD_NOT_IMPLEMENTED';
+  throw err;
+}
+
+afterEach(() => {
+  stubCpuUsage(REAL_CPU_USAGE);
+});
+
+describe('processCpuClock() under a runtime that stubs the method and throws', () => {
+  it('returns an UNAVAILABLE clock rather than one that throws on first use', () => {
+    stubCpuUsage(methodNotImplemented);
+
+    const clock = processCpuClock();
+    expect(clock.available).toBe(false);
+    // The label says which of the two failure shapes this was: it was there, and it threw.
+    expect(clock.source).toBe('process.cpuUsage (throws)');
+    // 🔴 And the span is a NaN, not a throw — NaN is what `createCpuRecorder` drops as
+    // "not a sample", where a 0 would be recorded as a confident measurement of no work.
+    const span = clock.start();
+    expect(Number.isNaN(span())).toBe(true);
+  });
+
+  it('🔴 leaves an app that mounts cpuBudget() SERVING, instead of 500 on every path', async () => {
+    stubCpuUsage(methodNotImplemented);
+
+    // Exactly the production wiring: no clock passed, so the middleware builds its own
+    // `processCpuClock()`, and it is mounted before everything else.
+    const app = new Hono();
+    const mw = cpuBudget();
+    app.use('*', mw);
+    app.get('/healthz', (c) => c.json({ ok: true }));
+
+    const res = await app.request('http://cpu-bench.invalid/healthz');
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+
+    // Nothing measurable was recorded — and that is the honest outcome, not a zero.
+    const report = mw.recorder.report();
+    expect(report.available).toBe(false);
+    expect(report.routes).toHaveLength(0);
+  });
+
+  it('probes the DELTA call too, not just the baseline one', () => {
+    // A stub that answers the zero-argument form and throws on `cpuUsage(before)` would
+    // pass a one-call probe and then throw at the END of the first request — the same
+    // outage, arriving one line later.
+    stubCpuUsage((before?: unknown) => {
+      if (before !== undefined) methodNotImplemented();
+      return { user: 1_000, system: 1_000 };
+    });
+
+    const clock = processCpuClock();
+    expect(clock.available).toBe(false);
+    expect(clock.source).toBe('process.cpuUsage (throws)');
+    expect(Number.isNaN(clock.start()())).toBe(true);
+  });
+
+  it('treats a stub that answers with a non-number as unavailable, never as zero', () => {
+    stubCpuUsage(() => ({ user: undefined, system: undefined }));
+
+    const clock = processCpuClock();
+    expect(clock.available).toBe(false);
+    expect(clock.source).toBe('process.cpuUsage (non-numeric)');
+    expect(Number.isNaN(clock.start()())).toBe(true);
+  });
+
+  it('still says (absent) when the method is genuinely missing', () => {
+    stubCpuUsage(undefined);
+
+    const clock = processCpuClock();
+    expect(clock.available).toBe(false);
+    expect(clock.source).toBe('process.cpuUsage (absent)');
+  });
+
+  // The direction that stops the fix from being "always unavailable": on this runtime the
+  // method works, and the clock must still measure. Without this, every case above passes
+  // against a `processCpuClock()` that returned `unavailableCpuClock()` unconditionally.
+  it('is AVAILABLE and measures on a runtime where the method really works', () => {
+    const clock = processCpuClock();
+    expect(clock.available).toBe(true);
+    expect(clock.source).toBe('process.cpuUsage');
+    expect(clock.proxy).toBe(true);
+
+    const span = clock.start();
+    let acc = 0;
+    for (let i = 0; i < 2_000_000; i += 1) acc += Math.sqrt(i % 13);
+    expect(acc).toBeGreaterThan(0);
+    const cpuMs = span();
+    expect(Number.isFinite(cpuMs)).toBe(true);
+    expect(cpuMs).toBeGreaterThan(0);
+  });
+});

package/src/server/bench/cpuClock.ts

@@ -43,10 +43,14 @@ export interface CpuClock {
  * That is why {@link runCpuBench} drives its cases SERIALLY — a serial driver is what
  * makes this proxy sound enough to gate on. Mounted in production it is advisory: useful
  * for ranking routes, not for a billing claim.
+ *
+ * Where the runtime has no such reading, this returns {@link unavailableCpuClock} — a
+ * clock, never a throw. {@link probeProcessCpuUsage} is what decides, and it decides by
+ * CALLING.
  */
 export function processCpuClock(): CpuClock {
-  const usable = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
-  if (!usable) return unavailableCpuClock('process.cpuUsage (absent)');
+  const probe = probeProcessCpuUsage();
+  if (!probe.ok) return unavailableCpuClock(`process.cpuUsage (${probe.why})`);
   return {
     source: 'process.cpuUsage',
     proxy: true,
@@ -61,6 +65,55 @@ export function processCpuClock(): CpuClock {
   };
 }
 
+/**
+ * 🔴 **Is `process.cpuUsage()` a clock here? Answered by CALLING it, never by `typeof`.**
+ *
+ * Measured 2026-09-19 on the first real deploy of a Worker mounting `cpuBudget()`: under
+ * `nodejs_compat`, workerd's strategy for the parts of `node:process` it does not implement
+ * is to PROVIDE the method and throw when it is called —
+ *
+ * ```
+ * Error [ERR_METHOD_NOT_IMPLEMENTED]: The process.cpuUsage method is not implemented
+ *     at process.cpuUsage (node-internal:public_process:235:11)
+ * ```
+ *
+ * — so `typeof process.cpuUsage === 'function'` answers *yes* about the one runtime the
+ * probe exists to answer *no* about. The clock that came back threw on first use, and
+ * because `cpuBudget()` is mounted FIRST by design, the throw landed in front of the whole
+ * app: every path 500, with 843 green tests behind it, because `bun test` runs where the
+ * method works.
+ *
+ * This is a capability CLASS, not one method: `nodejs_compat` stubs a great deal of
+ * `node:process`, `node:os` and `node:v8` the same way. `src/nodeBuiltinsAreProbedByCalling.spec.ts`
+ * is the check that keeps a `typeof` gate from coming back anywhere in this library.
+ *
+ * Both call shapes are exercised, because the span uses both and only one of them is
+ * probed by the first: `cpuUsage()` for the baseline and `cpuUsage(before)` for the delta.
+ * That costs two calls at wiring time — the same trade {@link workerCpuClock} argues for on
+ * the other side, and the alternative is a gate that reads zero for ever.
+ */
+function probeProcessCpuUsage(): { ok: true } | { ok: false; why: string } {
+  // Present-but-throwing and absent are both unavailable; the distinction only LABELS the
+  // clock, and is never the decision — which is why this line may carry the excuse that
+  // `src/nodeBuiltinsAreProbedByCalling.spec.ts` refuses everywhere else.
+  // probe-by-calling:ignore — label only; the call below is what decides.
+  const present = typeof process !== 'undefined' && typeof process.cpuUsage === 'function';
+  let reading: number;
+  try {
+    // A bare `process` that does not exist throws a ReferenceError in here, which is the
+    // same answer as a method that throws: not a clock.
+    const before = process.cpuUsage();
+    const delta = process.cpuUsage(before);
+    reading = before.user + before.system + delta.user + delta.system;
+  } catch {
+    return { ok: false, why: present ? 'throws' : 'absent' };
+  }
+  // A stub that returns something non-numeric is no more usable than one that throws, and
+  // would otherwise reach the recorder as a confident 0.00 for every route.
+  if (!Number.isFinite(reading)) return { ok: false, why: 'non-numeric' };
+  return { ok: true };
+}
+
 /**
  * A clock over a CPU-ms reader the runtime supplies. `proxy: false` — this is the real
  * quantity Cloudflare bills, so a report built on it may be quoted as one.

package/src/server/bench/runBench.ts

@@ -34,6 +34,33 @@ export interface BenchCase {
    * that never ran — a green budget over a broken route.
    */
   expectStatus?: number | number[] | ((status: number) => boolean);
+  /**
+   * Called before EVERY iteration of this case — warm-up included. For a **destructive**
+   * route, rebuild the fixture here; without it the second call measures an empty database.
+   *
+   * 🔴 This is the hook a destructive route cannot be benched without. `runCpuBench` fires a
+   * case `warmup + iterations` times against ONE app instance, which is exactly right for a
+   * read and a lie for a purge: the first call runs against a populated library and the next
+   * twenty-nine against an empty one, so the p99 is a small number for the wrong reason and
+   * the budget it satisfies means nothing. `expectStatus` cannot catch it either — the second
+   * call legitimately answers 200 with `{ deleted: 0 }`.
+   *
+   * It is **per case**, not run-wide, so the cheap read cases pay nothing for it — neither
+   * the rebuild nor the accounting {@link runCpuBench} does around it.
+   *
+   * 🔴 **Its cost is not measured, and that is checked rather than assumed.** The recorder is
+   * written through by the `cpuBudget()` middleware inside `app.fetch`, so a hook that runs
+   * outside that call is already excluded by ordering — but ordering is an accident, and a
+   * fixture rebuild that cost 200 ms and got attributed to the route would make this feature
+   * a worse lie than the hole it closes. So {@link runCpuBench} refuses a hook that drives
+   * the app under bench (see the error it throws), and `cpuBudget.spec.ts` proves a hook that
+   * burns real CPU leaves the route's number alone.
+   *
+   * `iteration` is 0-based and monotonic across the WHOLE case, warm-up first: warm-up gets
+   * `0 … warmup-1` and the measured pass continues from `warmup`. A hook that seeds ids from
+   * it therefore never collides between the two passes.
+   */
+  beforeEach?: (c: BenchCase, iteration: number) => void | Promise<void>;
 }
 
 export interface RunCpuBenchOpts {
@@ -73,6 +100,41 @@ function describe(c: BenchCase): string {
   return `${(c.method ?? 'GET').toUpperCase()} ${c.path}`;
 }
 
+/**
+ * Every request the recorder has attributed to any route so far. `samples` counts what was
+ * SEEN rather than what the reservoir retained, so this only ever goes up within a phase.
+ */
+function totalSamples(recorder: RunCpuBenchOpts['recorder']): number {
+  let n = 0;
+  for (const r of recorder.report().routes) n += r.samples;
+  return n;
+}
+
+/**
+ * Run a case's {@link BenchCase.beforeEach}, and prove it stayed out of the histogram.
+ *
+ * 🔴 The obvious way to rebuild a fixture is to drive the app that already has the routes —
+ * `POST /api/upload` thirty times to re-seed a library. Those requests go through
+ * `cpuBudget()` like any other, so the rebuild lands in the report as real samples on real
+ * routes, and the destructive route this hook exists to measure honestly is now benched
+ * beside rows nobody asked for. Refusing it here is cheap and only costs a case that has a
+ * hook at all.
+ */
+async function prepare(opts: RunCpuBenchOpts, c: BenchCase, iteration: number): Promise<void> {
+  if (!c.beforeEach) return;
+  const before = totalSamples(opts.recorder);
+  await c.beforeEach(c, iteration);
+  const after = totalSamples(opts.recorder);
+  if (after !== before) {
+    throw new Error(
+      `cpu-bench: ${describe(c)}'s beforeEach drove ${after - before} request(s) through the ` +
+        'app under bench, so the fixture rebuild is now IN the measurement it exists to keep ' +
+        'out of it. Rebuild the fixture directly — against the database, the store, the ' +
+        'seed helper — never through app.fetch.',
+    );
+  }
+}
+
 async function fire(opts: RunCpuBenchOpts, c: BenchCase): Promise<void> {
   const method = (c.method ?? c.init?.method ?? 'GET').toUpperCase();
   const req = new Request(`${opts.origin ?? BENCH_ORIGIN}${c.path}`, { ...c.init, method });
@@ -95,15 +157,24 @@ export async function runCpuBench(opts: RunCpuBenchOpts): Promise<CpuBudgetRepor
   const warmup = opts.warmup ?? 5;
   if (!(iterations > 0)) throw new Error('runCpuBench: iterations must be > 0');
 
+  // `beforeEach` runs over the warm-up too, deliberately. Warm-up exists to reach a handler's
+  // steady state, and a destructive route warmed against the empty database it emptied warms
+  // the wrong branch — the loop the p99 is about never runs.
   for (const c of opts.cases) {
-    for (let i = 0; i < warmup; i += 1) await fire(opts, c);
+    for (let i = 0; i < warmup; i += 1) {
+      await prepare(opts, c, i);
+      await fire(opts, c);
+    }
   }
   // 🔴 Everything above was warm-up. Discard it — measuring it is the bug this guards.
   opts.recorder.reset();
 
   for (const c of opts.cases) {
     const n = c.iterations ?? iterations;
-    for (let i = 0; i < n; i += 1) await fire(opts, c);
+    for (let i = 0; i < n; i += 1) {
+      await prepare(opts, c, warmup + i);
+      await fire(opts, c);
+    }
   }
 
   return opts.recorder.report();

package/src/server/d1/index.ts

@@ -39,7 +39,7 @@ export {
 // that does not use the query builder — which per `../db/kysely.ts`'s own header is most
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
-export { type InvocationD1, perInvocation } from './invocation';
+export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export {