cursedbelt-server 1.1.0 → 2.1.0

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

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  DAYS_PER_MONTH,
+  DEFAULT_ROUTE_CPU_BUDGET_MS,
+  deriveCpuBudgetMs,
+  monthlyOverageUsd,
+  OWNER_PROJECTED_REQUESTS_PER_DAY,
+  resolveBudget,
+  validateCpuBudgetConfig,
+  WORKERS_PAID_INCLUDED_CPU_MS,
+} from './budget';
+import { percentile } from './recorder';
+
+describe('the derivation', () => {
+  it('derives 9.9 CPU-ms from the Workers Paid allowance and the projected traffic', () => {
+    // 30,000,000 CPU-ms ÷ (100,000/day × 30.4375 days) = 9.856…
+    const raw = deriveCpuBudgetMs();
+    expect(raw).toBeCloseTo(9.856, 2);
+    expect(DEFAULT_ROUTE_CPU_BUDGET_MS).toBe(9.9);
+  });
+
+  it('is a FUNCTION of traffic, so the number moves when the measurement replaces the guess', () => {
+    // Twice the traffic halves what each request may spend. This is the call the outcome
+    // asks for once an app is live — not a constant somebody has to remember to edit.
+    expect(deriveCpuBudgetMs({ requestsPerDay: 200_000 })).toBeCloseTo(4.928, 2);
+    expect(deriveCpuBudgetMs({ requestsPerDay: 10_000 })).toBeCloseTo(98.56, 1);
+    expect(deriveCpuBudgetMs({ requestsPerMonth: 30_000_000 })).toBe(1);
+  });
+
+  it('holds the owner projection it was derived from, so a reader can check the arithmetic', () => {
+    expect(OWNER_PROJECTED_REQUESTS_PER_DAY * DAYS_PER_MONTH).toBeCloseTo(3_043_750, 0);
+    expect(WORKERS_PAID_INCLUDED_CPU_MS).toBe(30_000_000);
+  });
+
+  it('refuses a zero/negative request volume rather than returning Infinity', () => {
+    expect(() => deriveCpuBudgetMs({ requestsPerMonth: 0 })).toThrow(/must be > 0/);
+  });
+});
+
+describe('what going over actually costs', () => {
+  it('prices the overage — 3× the CPU budget at this traffic is about $1.20/month', () => {
+    const requestsPerMonth = OWNER_PROJECTED_REQUESTS_PER_DAY * DAYS_PER_MONTH;
+    const { cpuUsd, requestsUsd, totalUsd } = monthlyOverageUsd({
+      requestsPerMonth,
+      meanCpuMsPerRequest: DEFAULT_ROUTE_CPU_BUDGET_MS * 3,
+    });
+    // Requests are still well inside the included 10 M, so the whole bill is CPU.
+    expect(requestsUsd).toBe(0);
+    expect(cpuUsd).toBeCloseTo(1.2, 1);
+    expect(totalUsd).toBeCloseTo(1.2, 1);
+  });
+
+  it('charges nothing while both allowances are unspent', () => {
+    const { totalUsd } = monthlyOverageUsd({
+      requestsPerMonth: 1_000_000,
+      meanCpuMsPerRequest: 5,
+    });
+    expect(totalUsd).toBe(0);
+  });
+});
+
+describe('declaring a budget', () => {
+  it('prefers a method-specific key over a path-wide one', () => {
+    const config = { routes: { 'POST /api/x': 40, '/api/x': 2 } };
+    expect(resolveBudget(config, 'POST', '/api/x').cpuMs).toBe(40);
+    expect(resolveBudget(config, 'GET', '/api/x').cpuMs).toBe(2);
+  });
+
+  it('falls through to the default and says it was not declared', () => {
+    const r = resolveBudget({}, 'GET', '/whatever');
+    expect(r.cpuMs).toBe(DEFAULT_ROUTE_CPU_BUDGET_MS);
+    expect(r.declared).toBe(false);
+  });
+
+  it('carries an exemption through as a null ceiling plus its reason', () => {
+    const r = resolveBudget(
+      { routes: { 'POST /unlock': { exempt: true, reason: 'argon2id KDF' } } },
+      'POST',
+      '/unlock',
+    );
+    expect(r.cpuMs).toBeNull();
+    expect(r.exemptReason).toBe('argon2id KDF');
+    expect(r.declared).toBe(true);
+  });
+
+  // 🔴 The rule the task names: an opt-out must justify itself.
+  it('REFUSES an exemption with no reason', () => {
+    expect(() =>
+      validateCpuBudgetConfig({
+        routes: { '/unlock': { exempt: true, reason: '  ' } },
+      }),
+    ).toThrow(/exempt with no reason/);
+  });
+
+  it('refuses a nonsense budget up front, not when the route is first hit', () => {
+    expect(() => validateCpuBudgetConfig({ routes: { '/a': 0 } })).toThrow(/must be > 0/);
+    expect(() => validateCpuBudgetConfig({ routes: { '/a': -3 } })).toThrow(/must be > 0/);
+    expect(() => validateCpuBudgetConfig({ defaultCpuMs: 0 })).toThrow(/defaultCpuMs/);
+  });
+});
+
+describe('percentiles', () => {
+  // 🔴 The reason the report is a p99 and not a mean, stated as a test: this exact
+  // distribution PASSES a 9.9 ms budget on its mean and FAILS it on its p99.
+  it('reports the tail the mean hides', () => {
+    const samples = [...Array(98).fill(1), 400, 400].sort((a, b) => a - b);
+    const mean = samples.reduce((a, b) => a + b, 0) / samples.length;
+    expect(mean).toBeCloseTo(8.98, 2);
+    expect(mean).toBeLessThan(DEFAULT_ROUTE_CPU_BUDGET_MS); // a mean-based gate: green
+    expect(percentile(samples, 99)).toBe(400); // a p99-based gate: red, correctly
+    expect(percentile(samples, 50)).toBe(1);
+  });
+
+  it('uses nearest-rank, so it never reports a cost no request actually paid', () => {
+    const s = [1, 2, 3, 4];
+    expect(percentile(s, 50)).toBe(2);
+    expect(percentile(s, 75)).toBe(3);
+    expect(percentile(s, 99)).toBe(4);
+    // An interpolating p75 would answer 3.25 — a number no sample equals.
+    expect(s).toContain(percentile(s, 75));
+  });
+
+  it('answers NaN for no samples rather than 0', () => {
+    expect(percentile([], 99)).toBeNaN();
+  });
+});

package/src/server/bench/budget.ts

@@ -0,0 +1,207 @@
+/**
+ * The CPU budget, DERIVED rather than asserted.
+ *
+ * ## Why CPU and not requests
+ *
+ * The Workers Paid plan (`developers.cloudflare.com/workers/platform/pricing/`) meters
+ * requests and CPU time as two SEPARATE included allowances:
+ *
+ *   · $5/month base
+ *   · 10 million requests included, then +$0.30 per additional million
+ *   · 30 million CPU-milliseconds included, then +$0.02 per additional million
+ *   · 30 s CPU limit per invocation (raisable to 5 min)
+ *   · duration: "No charge or limit for duration" — wall clock is NEVER billed
+ *
+ * 🔴 There is no 125 ms per-request ceiling and no wall-clock fallback. That was the
+ * retired Bundled/Unbound model. Nothing here should be reasoned about in wall time:
+ * an `await` on a subrequest costs duration, and duration is free.
+ *
+ * At the owner's projection of 100k requests/day the two allowances are not equally
+ * tight — requests run to 30 % of the included 10 M while CPU is the binding one, which
+ * is the whole reason this module exists.
+ *
+ * ## 🔴 The default is a PROJECTION until an app is live
+ *
+ * {@link DEFAULT_ROUTE_CPU_BUDGET_MS} falls out of {@link OWNER_PROJECTED_REQUESTS_PER_DAY},
+ * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
+ * function to re-run against real traffic — the re-derivation is a call, not a paragraph
+ * somebody has to remember to do.
+ */
+
+/** CPU-milliseconds included in the Workers Paid plan each month. */
+export const WORKERS_PAID_INCLUDED_CPU_MS = 30_000_000;
+
+/** Requests included in the Workers Paid plan each month. */
+export const WORKERS_PAID_INCLUDED_REQUESTS = 10_000_000;
+
+/** USD per additional million CPU-ms, once the included allowance is spent. */
+export const WORKERS_PAID_USD_PER_MILLION_CPU_MS = 0.02;
+
+/** USD per additional million requests, once the included allowance is spent. */
+export const WORKERS_PAID_USD_PER_MILLION_REQUESTS = 0.3;
+
+/**
+ * The owner's own projection, 2026-09-15. 🔴 A PROJECTION, not a measurement — the
+ * whole point of {@link deriveCpuBudgetMs} is to replace it once an app is serving.
+ */
+export const OWNER_PROJECTED_REQUESTS_PER_DAY = 100_000;
+
+/** 365.25 / 12 — the average calendar month, since billing is monthly. */
+export const DAYS_PER_MONTH = 30.4375;
+
+/**
+ * Derive the average CPU-ms a single request may spend before the fleet exceeds its
+ * included CPU allowance.
+ *
+ * 🔴 This is an AVERAGE-per-request allowance, not a per-invocation limit. A route may
+ * exceed it and cost nothing, provided cheap routes carry the mean. What it is for is
+ * ranking: a route whose p99 sits above the average budget is a route that cannot be
+ * allowed to become the common case.
+ */
+export function deriveCpuBudgetMs(
+  opts: {
+    /** Included CPU-ms per month. Default: the Workers Paid allowance. */
+    includedCpuMs?: number;
+    /** Measured (or projected) requests per month. */
+    requestsPerMonth?: number;
+    /** Measured (or projected) requests per day — converted with {@link DAYS_PER_MONTH}. */
+    requestsPerDay?: number;
+  } = {},
+): number {
+  const includedCpuMs = opts.includedCpuMs ?? WORKERS_PAID_INCLUDED_CPU_MS;
+  const requestsPerMonth =
+    opts.requestsPerMonth ??
+    (opts.requestsPerDay ?? OWNER_PROJECTED_REQUESTS_PER_DAY) * DAYS_PER_MONTH;
+  if (!(requestsPerMonth > 0)) {
+    throw new Error('deriveCpuBudgetMs: requestsPerMonth must be > 0');
+  }
+  return includedCpuMs / requestsPerMonth;
+}
+
+/**
+ * What a month costs in overage once the included allowances are spent. Used by the
+ * report so a violation carries a PRICE and not only a number — the honest framing is
+ * that going 3× over the CPU budget at this traffic is about $1.20/month, which is a
+ * reason to care about the outlier route and not a reason to panic.
+ */
+export function monthlyOverageUsd(opts: {
+  requestsPerMonth: number;
+  meanCpuMsPerRequest: number;
+}): { cpuUsd: number; requestsUsd: number; totalUsd: number } {
+  const cpuMs = opts.requestsPerMonth * opts.meanCpuMsPerRequest;
+  const cpuOver = Math.max(0, cpuMs - WORKERS_PAID_INCLUDED_CPU_MS);
+  const reqOver = Math.max(0, opts.requestsPerMonth - WORKERS_PAID_INCLUDED_REQUESTS);
+  const cpuUsd = (cpuOver / 1_000_000) * WORKERS_PAID_USD_PER_MILLION_CPU_MS;
+  const requestsUsd = (reqOver / 1_000_000) * WORKERS_PAID_USD_PER_MILLION_REQUESTS;
+  return { cpuUsd, requestsUsd, totalUsd: cpuUsd + requestsUsd };
+}
+
+/**
+ * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
+ *
+ * Generous for a JSON route, tight for anything that renders, parses or derives a key.
+ * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ */
+export const DEFAULT_ROUTE_CPU_BUDGET_MS = Math.round(deriveCpuBudgetMs() * 10) / 10;
+
+/** A route that is measured against a number. */
+export interface CpuBudgetLimit {
+  cpuMs: number;
+}
+
+/**
+ * A route that is deliberately NOT measured against the default.
+ *
+ * 🔴 `reason` is required by the type AND checked at runtime. An exemption whose
+ * justification is blank is the paragraph this module exists to replace — a silent
+ * opt-out is indistinguishable from a route nobody looked at.
+ */
+export interface CpuBudgetExemption {
+  exempt: true;
+  reason: string;
+  /**
+   * The exemption still records, and a p99 above this is reported as a NOTICE rather
+   * than a violation. Optional — an exemption with no ceiling is never surprising.
+   */
+  noticeAboveMs?: number;
+}
+
+export type RouteBudget = CpuBudgetLimit | CpuBudgetExemption | number;
+
+export interface CpuBudgetConfig {
+  /** Applied to any route without its own entry. Default: {@link DEFAULT_ROUTE_CPU_BUDGET_MS}. */
+  defaultCpuMs?: number;
+  /**
+   * Per-route budgets, keyed either `'GET /api/notes/:id'` (method-specific, wins) or
+   * `'/api/notes/:id'` (any method). Keys are matched against the same normalized route
+   * label the metrics tier uses, so `:params` are already collapsed.
+   */
+  routes?: Record<string, RouteBudget>;
+}
+
+export function isExemption(b: RouteBudget): b is CpuBudgetExemption {
+  return typeof b === 'object' && 'exempt' in b && b.exempt === true;
+}
+
+/** The resolved budget for one route label. */
+export interface ResolvedBudget {
+  /** The ceiling in CPU-ms, or `null` when the route is exempt. */
+  cpuMs: number | null;
+  exemptReason?: string;
+  noticeAboveMs?: number;
+  /** True when no explicit entry matched and the default was applied. */
+  declared: boolean;
+}
+
+/**
+ * 🔴 Validate the whole config up front rather than at the moment a route is hit. A
+ * blank exemption reason on a route nobody exercised in the bench would otherwise ship.
+ */
+export function validateCpuBudgetConfig(config: CpuBudgetConfig): void {
+  if (config.defaultCpuMs !== undefined && !(config.defaultCpuMs > 0)) {
+    throw new Error(`cpuBudget: defaultCpuMs must be > 0, got ${config.defaultCpuMs}`);
+  }
+  for (const [key, budget] of Object.entries(config.routes ?? {})) {
+    if (isExemption(budget)) {
+      if (typeof budget.reason !== 'string' || budget.reason.trim() === '') {
+        throw new Error(
+          `cpuBudget: route '${key}' is exempt with no reason. An opt-out must name why — ` +
+            'that is the difference between a decision and an oversight.',
+        );
+      }
+      if (budget.noticeAboveMs !== undefined && !(budget.noticeAboveMs > 0)) {
+        throw new Error(`cpuBudget: route '${key}' has noticeAboveMs ≤ 0`);
+      }
+      continue;
+    }
+    const cpuMs = typeof budget === 'number' ? budget : budget.cpuMs;
+    if (!(cpuMs > 0)) {
+      throw new Error(`cpuBudget: route '${key}' has a budget of ${cpuMs}; it must be > 0`);
+    }
+  }
+}
+
+/** Resolve `method` + `route` against the config. Method-specific keys win. */
+export function resolveBudget(
+  config: CpuBudgetConfig,
+  method: string,
+  route: string,
+): ResolvedBudget {
+  const routes = config.routes ?? {};
+  const explicit = routes[`${method} ${route}`] ?? routes[route];
+  if (explicit === undefined) {
+    return { cpuMs: config.defaultCpuMs ?? DEFAULT_ROUTE_CPU_BUDGET_MS, declared: false };
+  }
+  if (isExemption(explicit)) {
+    return {
+      cpuMs: null,
+      exemptReason: explicit.reason,
+      noticeAboveMs: explicit.noticeAboveMs,
+      declared: true,
+    };
+  }
+  return {
+    cpuMs: typeof explicit === 'number' ? explicit : explicit.cpuMs,
+    declared: true,
+  };
+}

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

@@ -0,0 +1,302 @@
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { assertCpuBudgets, checkCpuBudgets, formatCpuBudgetReport } from './assert';
+import { type CpuBudgetConfig, DEFAULT_ROUTE_CPU_BUDGET_MS } from './budget';
+import { cpuBudget } from './cpuBudget';
+import { fixedCpuClock, processCpuClock, unavailableCpuClock } from './cpuClock';
+import { createCpuRecorder } from './recorder';
+import { runCpuBench } from './runBench';
+
+/**
+ * 🔴 **The assertion must fire in BOTH directions or it is decoration.** A gate that can
+ * only pass is indistinguishable from no gate, and a gate that always fails gets deleted
+ * in a week. Everything below is one of those two directions.
+ *
+ * The end-to-end cases burn REAL CPU through a REAL Hono app, because the thing being
+ * proven is that the middleware attributes cost to the right route — which a mocked clock
+ * cannot show. The deterministic cases use `fixedCpuClock` for the edges, where a real
+ * timing would make the suite flaky for no extra truth.
+ */
+
+/** Burn approximately `ms` of CPU. Deliberately un-optimizable: the result escapes. */
+function burnCpu(ms: number): number {
+  const deadline = performance.now() + ms;
+  let acc = 0;
+  while (performance.now() < deadline) {
+    for (let i = 0; i < 2_000; i += 1) acc += Math.sqrt(i + acc % 7);
+  }
+  return acc;
+}
+
+const SLOW_MS = 30; // ~3× the 9.9 ms budget — far outside measurement noise.
+
+function buildApp(config: CpuBudgetConfig, clock = processCpuClock()) {
+  const recorder = createCpuRecorder({ clock, config });
+  const app = new Hono();
+  app.use('*', cpuBudget({ recorder }));
+  app.get('/api/cheap', (c) => c.json({ ok: true }));
+  app.get('/api/slow', (c) => c.json({ ok: true, acc: burnCpu(SLOW_MS) }));
+  app.post('/api/unlock', (c) => c.json({ ok: true, acc: burnCpu(SLOW_MS) }));
+  return { app, recorder };
+}
+
+describe('direction 1 — a route under budget PASSES', () => {
+  it('measures a cheap JSON route and asserts green', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 25,
+    });
+
+    expect(report.routes).toHaveLength(1);
+    const row = report.routes[0];
+    expect(row.key).toBe('GET /api/cheap');
+    expect(row.samples).toBe(25);
+    expect(row.p99).toBeLessThan(5);
+    // Does not throw — that IS the assertion under test.
+    expect(assertCpuBudgets(report)).toEqual([]);
+  });
+});
+
+describe('direction 2 — a route over budget FAILS, and names itself', () => {
+  it('reddens on a deliberately slow route and puts the route and its number in the message', async () => {
+    const { app, recorder } = buildApp({}); // no declaration → the 9.9 ms default applies
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/slow' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const row = report.routes[0];
+    expect(row.key).toBe('GET /api/slow');
+    expect(row.p99).toBeGreaterThan(DEFAULT_ROUTE_CPU_BUDGET_MS);
+
+    let message = '';
+    expect(() => {
+      try {
+        assertCpuBudgets(report);
+      } catch (err) {
+        message = (err as Error).message;
+        throw err;
+      }
+    }).toThrow(/over CPU budget/);
+
+    // 🔴 The failure names the ROUTE…
+    expect(message).toContain('GET /api/slow');
+    // …and its NUMBER, and the budget it broke.
+    expect(message).toMatch(/spent \d+\.\d+ CPU-ms at p99/);
+    expect(message).toContain('9.90 CPU-ms');
+    expect(message).toMatch(/\d+\.\d+×/);
+    // …and the whole table, so the reader does not have to go looking.
+    expect(message).toContain('p50');
+  });
+
+  it('attributes cost to the RIGHT route when a cheap and an expensive one share an app', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5, 'GET /api/slow': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }, { path: '/api/slow' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const cheap = report.routes.find((r) => r.route === '/api/cheap');
+    const slow = report.routes.find((r) => r.route === '/api/slow');
+    expect(cheap?.p99).toBeLessThan(5);
+    expect(slow?.p99).toBeGreaterThan(SLOW_MS * 0.5);
+
+    const violations = checkCpuBudgets(report);
+    expect(violations.map((v) => v.key)).toEqual(['GET /api/slow']);
+    // Worst offender is sorted to the top of the report.
+    expect(report.routes[0].route).toBe('/api/slow');
+  });
+});
+
+describe('the exemption — the KDF is the type specimen', () => {
+  it('lets a named exemption through while the same cost fails undeclared', async () => {
+    const config: CpuBudgetConfig = {
+      routes: {
+        'POST /api/unlock': {
+          exempt: true,
+          reason: 'argon2id KDF: 332 CPU-ms and 64 MiB measured — expensive on purpose',
+        },
+      },
+    };
+    const { app, recorder } = buildApp(config);
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ method: 'POST', path: '/api/unlock' }],
+      iterations: 20,
+      warmup: 3,
+    });
+
+    const row = report.routes[0];
+    expect(row.budgetMs).toBeNull();
+    expect(row.exemptReason).toContain('argon2id');
+    expect(row.p99).toBeGreaterThan(DEFAULT_ROUTE_CPU_BUDGET_MS); // genuinely over
+    expect(assertCpuBudgets(report)).toEqual([]); // and deliberately allowed
+
+    expect(formatCpuBudgetReport(report)).toContain('exempt: argon2id KDF');
+  });
+
+  it('still NOTICES an exempt route that crosses its own threshold, without failing', () => {
+    const recorder = createCpuRecorder({
+      clock: fixedCpuClock([500]),
+      config: {
+        routes: {
+          '/unlock': { exempt: true, reason: 'KDF', noticeAboveMs: 400 },
+        },
+      },
+    });
+    for (let i = 0; i < 25; i += 1) recorder.record('POST', '/unlock', 500);
+    const violations = checkCpuBudgets(recorder.report());
+    expect(violations).toHaveLength(1);
+    expect(violations[0].kind).toBe('exempt-notice');
+    expect(violations[0].fails).toBe(false);
+    expect(() => assertCpuBudgets(recorder.report())).not.toThrow();
+  });
+});
+
+describe('the ways a green could be a lie', () => {
+  it('FAILS a route it could not sample enough times to have a p99', () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([1]) });
+    for (let i = 0; i < 3; i += 1) recorder.record('GET', '/api/x', 1);
+    expect(() => assertCpuBudgets(recorder.report())).toThrow(/needs at least 20/);
+  });
+
+  it('FAILS when the clock could not measure at all, rather than passing on zero', () => {
+    const recorder = createCpuRecorder({ clock: unavailableCpuClock() });
+    recorder.record('GET', '/api/x', Number.NaN);
+    const report = recorder.report();
+    expect(report.routes).toHaveLength(0); // an unmeasurable request is not a sample
+    expect(() => assertCpuBudgets(report)).toThrow(/nothing could be measured/);
+    expect(assertCpuBudgets(report, { allowUnmeasurable: true })).toEqual([]);
+  });
+
+  it('FAILS an undeclared route under requireDeclared, so an app must budget every route', () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([1]) });
+    for (let i = 0; i < 25; i += 1) recorder.record('GET', '/api/undeclared', 1);
+    expect(() => assertCpuBudgets(recorder.report(), { requireDeclared: true })).toThrow(
+      /declares no CPU budget/,
+    );
+    // The same route passes without the flag — the default still applies.
+    expect(assertCpuBudgets(recorder.report())).toEqual([]);
+  });
+
+  // 🔴 A 404 costs no CPU. Without this guard the bench reports a beautiful number for a
+  // handler that never ran.
+  it('REFUSES to bench a route that errors, instead of reporting its cheap 404', async () => {
+    const { app, recorder } = buildApp({});
+    await expect(
+      runCpuBench({ app, recorder, cases: [{ path: '/api/does-not-exist' }], iterations: 5 }),
+    ).rejects.toThrow(/returned 404, which this case does not expect/);
+  });
+
+  it('can bench an error path deliberately, when the case says so', async () => {
+    const { app, recorder } = buildApp({});
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/does-not-exist', expectStatus: 404 }],
+      iterations: 20,
+      warmup: 2,
+    });
+    expect(report.routes[0].samples).toBe(20);
+  });
+});
+
+describe('honesty of the number', () => {
+  it('labels a local reading as a PROXY, in the report and in its formatting', async () => {
+    const { app, recorder } = buildApp({ routes: { 'GET /api/cheap': 5 } });
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 20,
+    });
+    expect(report.proxy).toBe(true);
+    expect(report.source).toBe('process.cpuUsage');
+    expect(formatCpuBudgetReport(report)).toContain('🔴 PROXY');
+    expect(formatCpuBudgetReport(report)).toContain('NOT Worker CPU-ms');
+  });
+
+  it('does NOT label a runtime-supplied reading as a proxy', () => {
+    let cpu = 0;
+    const recorder = createCpuRecorder({
+      clock: {
+        source: 'worker-runtime',
+        proxy: false,
+        available: true,
+        start: () => {
+          const before = cpu;
+          cpu += 1;
+          return () => cpu - before;
+        },
+      },
+    });
+    for (let i = 0; i < 25; i += 1) recorder.record('GET', '/x', 1);
+    const report = recorder.report();
+    expect(report.proxy).toBe(false);
+    expect(formatCpuBudgetReport(report)).toContain('runtime-reported Worker CPU-ms');
+  });
+});
+
+describe('the bench runner', () => {
+  it('DISCARDS warm-up, so a cold first call cannot become the p99', async () => {
+    // The first span through this clock reads 1000; every later one reads 1. With warm-up
+    // discarded the route is cheap; without it, one cold call owns the p99 of 20 samples.
+    const clock = fixedCpuClock([1000, 1, 1]);
+    const recorder = createCpuRecorder({ clock, config: { routes: { '/api/cheap': 5 } } });
+    const app = new Hono();
+    app.use('*', cpuBudget({ recorder }));
+    app.get('/api/cheap', (c) => c.json({ ok: true }));
+
+    const report = await runCpuBench({
+      app,
+      recorder,
+      cases: [{ path: '/api/cheap' }],
+      iterations: 20,
+      warmup: 1,
+    });
+    expect(report.routes[0].max).toBe(1);
+    expect(report.routes[0].samples).toBe(20);
+    expect(assertCpuBudgets(report)).toEqual([]);
+  });
+
+  // A handler that is expensive only on its error path is exactly what a budget should
+  // catch, so the sample must survive the throw. The middleware re-throws unchanged and
+  // Hono's own onError turns it into the 500 — the CPU is attributed either way.
+  it('records CPU even when the handler throws, and leaves error handling alone', async () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([42]) });
+    const seen: string[] = [];
+    const app = new Hono();
+    app.onError((err, c) => {
+      seen.push((err as Error).message);
+      return c.json({ error: 'handled' }, 500);
+    });
+    app.use('*', cpuBudget({ recorder }));
+    app.get('/boom', () => {
+      throw new Error('kaboom');
+    });
+
+    const res = await app.request('http://cpu-bench.invalid/boom');
+    expect(res.status).toBe(500);
+    // Re-thrown unchanged: the app's own onError saw the original error.
+    expect(seen).toEqual(['kaboom']);
+
+    const report = recorder.report();
+    expect(report.routes[0].key).toBe('GET /boom');
+    expect(report.routes[0].max).toBe(42);
+  });
+
+  it('refuses a run with no cases rather than passing vacuously', async () => {
+    const { app, recorder } = buildApp({});
+    await expect(runCpuBench({ app, recorder, cases: [] })).rejects.toThrow(/no cases/);
+  });
+});