cursedbelt-server 4.1.0 → 4.3.0

package/dist/server/d1/local.js

@@ -15,9 +15,16 @@
  */
 import { assertBatchSize, assertWithinLimits } from './limits';
 import { D1UnsupportedError, } from './types';
-import { makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
+import { isPureReadSql, makeMeta, normalizeBinds, normalizeRows, normalizeValue } from './values';
 /** Shared clock, so `meta.duration` means the same thing on both sides of the seam. */
 const now = () => performance.now();
+/**
+ * Rows changed on this CONNECTION since it was opened — monotonic, so a difference across
+ * one statement is that statement's own count. Used only where `.run()` cannot report it.
+ */
+const totalChanges = (db) => db.query('SELECT total_changes() AS n').get().n;
+/** The connection's last inserted rowid, which is what D1 reports in `meta.last_row_id`. */
+const lastInsertRowid = (db) => db.query('SELECT last_insert_rowid() AS r').get().r;
 class LocalStatement {
     db;
     sql;
@@ -37,11 +44,49 @@ class LocalStatement {
     }
     allSync() {
         const started = now();
-        const rows = this.stmt().all(...this.params);
+        const stmt = this.stmt();
+        // 🔴 A statement with NO result columns cannot return rows, so `.run()` is both the
+        // cheaper path and the only one that reports `changes` at all — `.all()` does not.
+        // `columnNames` is `bun:sqlite`'s own answer and is exact: `[]` for INSERT/UPDATE/
+        // DELETE, populated for SELECT and for anything carrying RETURNING (probed 2026-09-17).
+        if (stmt.columnNames.length === 0) {
+            const res = stmt.run(...this.params);
+            return {
+                results: [],
+                success: true,
+                meta: makeMeta({
+                    changes: res.changes,
+                    last_row_id: res.lastInsertRowid,
+                    duration: now() - started,
+                }),
+            };
+        }
+        const rowsOf = () => this.stmt().all(...this.params);
+        // A pure read changed nothing, and its counters are the PREVIOUS statement's — see
+        // `isPureReadSql`. Reporting zero is the measurement, not a default.
+        if (isPureReadSql(this.sql)) {
+            const rows = rowsOf();
+            return {
+                results: normalizeRows(rows),
+                success: true,
+                meta: makeMeta({ duration: now() - started }),
+            };
+        }
+        // Returns rows AND may write: `INSERT … RETURNING`, `WITH … UPDATE … RETURNING`.
+        // `total_changes()` is cumulative for the connection, so the DIFFERENCE across the
+        // statement is this statement's own count — the one reading that stays correct when
+        // the statement is neither a plain read nor a plain write.
+        const before = totalChanges(this.db);
+        const rows = rowsOf();
+        const changes = totalChanges(this.db) - before;
         return {
             results: normalizeRows(rows),
             success: true,
-            meta: makeMeta({ duration: now() - started }),
+            meta: makeMeta({
+                changes,
+                last_row_id: changes > 0 ? lastInsertRowid(this.db) : null,
+                duration: now() - started,
+            }),
         };
     }
     async first(column) {

package/dist/server/d1/values.d.ts

@@ -1,6 +1,6 @@
 /**
- * The one place that decides what a bound parameter and a returned column MEAN, shared by
- * both drivers.
+ * The one place that decides what a bound parameter, a returned column and a statement's
+ * own `meta` MEAN, shared by both drivers.
  *
  * 🔴 **Both drivers call these, and that is why the identical-shapes test can pass.** If
  * the local driver normalized its own way and the remote driver normalized its own way,
@@ -23,6 +23,23 @@ import { type D1LikeBindable, type D1LikeMeta, type D1LikeValue } from './types'
 export declare function normalizeBind(value: unknown, index: number): D1LikeBindable;
 /** Normalize a whole parameter list, reporting the offending position on failure. */
 export declare const normalizeBinds: (values: readonly unknown[]) => D1LikeBindable[];
+/**
+ * Is this statement a PURE READ — one that cannot possibly have changed a row?
+ *
+ * 🔴 Measured 2026-09-17, and this is why the question has to be asked at all:
+ * SQLite's `changes()` and `last_insert_rowid()` are **connection-wide and sticky**.
+ * After a plain `SELECT` they still read the counters left by the last write — probed
+ * here, a `SELECT` following a 1-row insert reports `changes = 1`. So those counters may
+ * only ever be attributed to a statement that actually wrote something, and a driver
+ * that reads them after a read invents a `changes` out of the previous statement's.
+ *
+ * Only a leading `SELECT` is claimed, because that is the one keyword that is
+ * unambiguous: `WITH … INSERT … RETURNING` and `INSERT … RETURNING` both return rows AND
+ * write. Anything this returns `false` for is measured exactly instead (see
+ * `local.ts`), so a statement shape this does not recognise costs two extra queries —
+ * never a wrong number.
+ */
+export declare const isPureReadSql: (sql: string) => boolean;
 /**
  * Normalize one column value coming BACK from a driver.
  *

package/dist/server/d1/values.js

@@ -1,6 +1,6 @@
 /**
- * The one place that decides what a bound parameter and a returned column MEAN, shared by
- * both drivers.
+ * The one place that decides what a bound parameter, a returned column and a statement's
+ * own `meta` MEAN, shared by both drivers.
  *
  * 🔴 **Both drivers call these, and that is why the identical-shapes test can pass.** If
  * the local driver normalized its own way and the remote driver normalized its own way,
@@ -69,6 +69,25 @@ export function normalizeBind(value, index) {
 }
 /** Normalize a whole parameter list, reporting the offending position on failure. */
 export const normalizeBinds = (values) => values.map((v, i) => normalizeBind(v, i));
+/** Leading whitespace and SQL comments, which sit in front of the real first keyword. */
+const LEADING_NOISE = /^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)+/;
+/**
+ * Is this statement a PURE READ — one that cannot possibly have changed a row?
+ *
+ * 🔴 Measured 2026-09-17, and this is why the question has to be asked at all:
+ * SQLite's `changes()` and `last_insert_rowid()` are **connection-wide and sticky**.
+ * After a plain `SELECT` they still read the counters left by the last write — probed
+ * here, a `SELECT` following a 1-row insert reports `changes = 1`. So those counters may
+ * only ever be attributed to a statement that actually wrote something, and a driver
+ * that reads them after a read invents a `changes` out of the previous statement's.
+ *
+ * Only a leading `SELECT` is claimed, because that is the one keyword that is
+ * unambiguous: `WITH … INSERT … RETURNING` and `INSERT … RETURNING` both return rows AND
+ * write. Anything this returns `false` for is measured exactly instead (see
+ * `local.ts`), so a statement shape this does not recognise costs two extra queries —
+ * never a wrong number.
+ */
+export const isPureReadSql = (sql) => /^select\b/i.test(sql.replace(LEADING_NOISE, ''));
 /**
  * Normalize one column value coming BACK from a driver.
  *

package/dist/server/middleware/bodyLimit.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Reading a request body without first agreeing how big it may be.
+ *
+ * ── Why this is one function rather than one per app (2026-07-27) ────────────
+ * The two apps behind the shared owner-auth were inconsistently hardened, in a
+ * way an adversarial review found and neither test suite could:
+ *
+ * - the companion app (since folded into `apps/orch`) read `c.req.text()`,
+ *   checked the length, and returned 413 BEFORE parsing — correct.
+ * - `apps/roms` called `await c.req.json()` first and checked the size deep
+ *   inside the save-state store — i.e. it buffered and parsed an arbitrary body
+ *   into a process whose unit caps at 300 MB of memory before forming an
+ *   opinion about its size.
+ *
+ * Both went through {@link readBoundedJson} after that. The guard is one
+ * function so the posture cannot diverge again, and it is deliberately the
+ * *last* line of defense: a proxy's `client_max_body_size` refuses an oversized
+ * body at the edge, and this refuses it if the proxy is absent, misconfigured,
+ * or bypassed — which is exactly the case in dev, in `preview:prod`, and for any
+ * request that reaches the loopback port directly.
+ *
+ * ── Where it came from (2026-09-17) ──────────────────────────────────────────
+ * Five apps — `roms`, `family`, `music`, `vault`, `collections` — carried this
+ * file byte-for-byte identical (`b36d0eedee7a`), which is the posture diverging
+ * again, only more slowly and with nothing watching: a repo's gate proves that
+ * repo, so five green gates is what five copies of a security guard look like
+ * from the outside. Confirmed identical with `shasum -a256` before the move, so
+ * there was no fork to reconcile and nothing was dropped.
+ *
+ * 🔴 It is published as the LEAF subpath `cursedbelt-server/body-limit`, never
+ * through the `./middleware` barrel — that barrel drags `hono` and the error
+ * envelope, and this module's whole promise is that it imports NOTHING. The
+ * source is a `{ req: { text() } }` / `{ req: { arrayBuffer() } }` /
+ * `{ req: { header() } }` structural type rather than a Hono context, so a
+ * caller needs no framework to use it and a test needs none to exercise it.
+ * `src/leafSubpathsImportNothing.spec.ts` is what holds that promise.
+ */
+/** What {@link readBoundedBytes} gives back. */
+export type BoundedBytes = {
+    ok: true;
+    value: Uint8Array;
+} | {
+    ok: false;
+    status: 413 | 400;
+    error: string;
+};
+/** The minimum a route needs to hand over a raw body. */
+export interface BodyBytesSource {
+    req: {
+        arrayBuffer(): Promise<ArrayBuffer>;
+    };
+}
+/** What {@link readBoundedJson} gives back — a discriminated result, never a throw. */
+export type BoundedJson<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    status: 413;
+    error: string;
+} | {
+    ok: false;
+    status: 400;
+    error: string;
+};
+export interface BoundedJsonOptions {
+    /** Hard ceiling on the raw body, in bytes. */
+    maxBytes: number;
+    /** What to call the payload in the error message (e.g. "save state"). */
+    label?: string;
+}
+/** The minimum a route needs from Hono's context — kept structural so tests need no Hono. */
+export interface BodyTextSource {
+    req: {
+        text(): Promise<string>;
+    };
+}
+/** What {@link readBoundedText} gives back. Same shape, minus the parse failure. */
+export type BoundedText = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    status: 413 | 400;
+    error: string;
+};
+/**
+ * Read a body as TEXT, refusing anything over `maxBytes`.
+ *
+ * The sibling of {@link readBoundedJson}, for a payload that IS the text rather
+ * than a document containing it — `apps/patterns`' chunked sends put their
+ * metadata in the query string and the chunk in the raw body, which spares a
+ * megabyte-scale caller from JSON-escaping every piece and spares this process
+ * from parsing what it is only going to concatenate.
+ *
+ * Same byte-not-character measurement, and for the same reason: it is the number
+ * the proxy in front of this is enforcing.
+ */
+export declare function readBoundedText(c: BodyTextSource, options: BoundedJsonOptions): Promise<BoundedText>;
+/**
+ * Read a body as RAW BYTES, refusing anything over `maxBytes`.
+ *
+ * The third member of the family, for a payload that is neither JSON nor text:
+ * roms' ROM-upload chunks are cartridge bytes, and routing them through
+ * {@link readBoundedText} would decode arbitrary binary as UTF-8 — which is
+ * lossy (every invalid sequence becomes U+FFFD) and measures a size that is not
+ * the size the proxy in front is enforcing.
+ *
+ * A `Content-Length` claim is deliberately NOT trusted here: it is a header, and
+ * the guard has to hold against a body that disagrees with it. The measurement is
+ * the buffer that actually arrived.
+ */
+export declare function readBoundedBytes(c: BodyBytesSource, options: BoundedJsonOptions): Promise<BoundedBytes>;
+/** The minimum {@link refuseOversizedBody} needs — a header lookup, nothing else. */
+export interface BodyHeaderSource {
+    req: {
+        header(name: string): string | undefined;
+    };
+}
+/**
+ * Refuse a body by its DECLARED `Content-Length`, without reading it.
+ *
+ * The fourth member of the family, and the only one for a body that cannot be
+ * buffered first: a `multipart/form-data` upload. The other three measure the
+ * bytes that actually arrived, which is strictly better — but they get to,
+ * because they buffer. `c.req.formData()` gives no such opportunity: by the time
+ * it resolves, the whole upload is already in a process whose unit caps at
+ * 300 MB of memory, which is the thing the limit exists to prevent.
+ *
+ * So this trusts the header, and the docblock says so plainly. A liar gets
+ * through to the buffering call — but a liar was always going to, and this still
+ * turns the honest 3 GB folder-drop (the actual failure shape) into a refusal
+ * the app can explain instead of an OOM or an nginx HTML 413 the app never sees.
+ * It is a companion to the proxy's `client_max_body_size`, never a replacement.
+ *
+ * A missing or unparseable header is NOT a refusal: chunked requests omit it
+ * legitimately, and refusing them would break a correct client to catch a
+ * dishonest one.
+ */
+export declare function refuseOversizedBody(c: BodyHeaderSource, options: BoundedJsonOptions): {
+    status: 413;
+    error: string;
+} | null;
+/**
+ * Read a JSON body, refusing anything over `maxBytes` before parsing it.
+ *
+ * The size is measured in BYTES, not characters. `String.length` counts UTF-16
+ * code units, so a body of 4-byte emoji measures half its true size that way —
+ * which would let a caller past a byte limit the proxy is enforcing in real
+ * bytes, and produce the mismatch this module exists to close.
+ */
+export declare function readBoundedJson<T = unknown>(c: BodyTextSource, options: BoundedJsonOptions): Promise<BoundedJson<T>>;

package/dist/server/middleware/bodyLimit.js

@@ -0,0 +1,161 @@
+/**
+ * Reading a request body without first agreeing how big it may be.
+ *
+ * ── Why this is one function rather than one per app (2026-07-27) ────────────
+ * The two apps behind the shared owner-auth were inconsistently hardened, in a
+ * way an adversarial review found and neither test suite could:
+ *
+ * - the companion app (since folded into `apps/orch`) read `c.req.text()`,
+ *   checked the length, and returned 413 BEFORE parsing — correct.
+ * - `apps/roms` called `await c.req.json()` first and checked the size deep
+ *   inside the save-state store — i.e. it buffered and parsed an arbitrary body
+ *   into a process whose unit caps at 300 MB of memory before forming an
+ *   opinion about its size.
+ *
+ * Both went through {@link readBoundedJson} after that. The guard is one
+ * function so the posture cannot diverge again, and it is deliberately the
+ * *last* line of defense: a proxy's `client_max_body_size` refuses an oversized
+ * body at the edge, and this refuses it if the proxy is absent, misconfigured,
+ * or bypassed — which is exactly the case in dev, in `preview:prod`, and for any
+ * request that reaches the loopback port directly.
+ *
+ * ── Where it came from (2026-09-17) ──────────────────────────────────────────
+ * Five apps — `roms`, `family`, `music`, `vault`, `collections` — carried this
+ * file byte-for-byte identical (`b36d0eedee7a`), which is the posture diverging
+ * again, only more slowly and with nothing watching: a repo's gate proves that
+ * repo, so five green gates is what five copies of a security guard look like
+ * from the outside. Confirmed identical with `shasum -a256` before the move, so
+ * there was no fork to reconcile and nothing was dropped.
+ *
+ * 🔴 It is published as the LEAF subpath `cursedbelt-server/body-limit`, never
+ * through the `./middleware` barrel — that barrel drags `hono` and the error
+ * envelope, and this module's whole promise is that it imports NOTHING. The
+ * source is a `{ req: { text() } }` / `{ req: { arrayBuffer() } }` /
+ * `{ req: { header() } }` structural type rather than a Hono context, so a
+ * caller needs no framework to use it and a test needs none to exercise it.
+ * `src/leafSubpathsImportNothing.spec.ts` is what holds that promise.
+ */
+/**
+ * Read a body as TEXT, refusing anything over `maxBytes`.
+ *
+ * The sibling of {@link readBoundedJson}, for a payload that IS the text rather
+ * than a document containing it — `apps/patterns`' chunked sends put their
+ * metadata in the query string and the chunk in the raw body, which spares a
+ * megabyte-scale caller from JSON-escaping every piece and spares this process
+ * from parsing what it is only going to concatenate.
+ *
+ * Same byte-not-character measurement, and for the same reason: it is the number
+ * the proxy in front of this is enforcing.
+ */
+export async function readBoundedText(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let raw;
+    try {
+        raw = await c.req.text();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    const bytes = new TextEncoder().encode(raw).length;
+    if (bytes > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Read a body as RAW BYTES, refusing anything over `maxBytes`.
+ *
+ * The third member of the family, for a payload that is neither JSON nor text:
+ * roms' ROM-upload chunks are cartridge bytes, and routing them through
+ * {@link readBoundedText} would decode arbitrary binary as UTF-8 — which is
+ * lossy (every invalid sequence becomes U+FFFD) and measures a size that is not
+ * the size the proxy in front is enforcing.
+ *
+ * A `Content-Length` claim is deliberately NOT trusted here: it is a header, and
+ * the guard has to hold against a body that disagrees with it. The measurement is
+ * the buffer that actually arrived.
+ */
+export async function readBoundedBytes(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let buffer;
+    try {
+        buffer = await c.req.arrayBuffer();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    if (buffer.byteLength > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${buffer.byteLength} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    return { ok: true, value: new Uint8Array(buffer) };
+}
+/**
+ * Refuse a body by its DECLARED `Content-Length`, without reading it.
+ *
+ * The fourth member of the family, and the only one for a body that cannot be
+ * buffered first: a `multipart/form-data` upload. The other three measure the
+ * bytes that actually arrived, which is strictly better — but they get to,
+ * because they buffer. `c.req.formData()` gives no such opportunity: by the time
+ * it resolves, the whole upload is already in a process whose unit caps at
+ * 300 MB of memory, which is the thing the limit exists to prevent.
+ *
+ * So this trusts the header, and the docblock says so plainly. A liar gets
+ * through to the buffering call — but a liar was always going to, and this still
+ * turns the honest 3 GB folder-drop (the actual failure shape) into a refusal
+ * the app can explain instead of an OOM or an nginx HTML 413 the app never sees.
+ * It is a companion to the proxy's `client_max_body_size`, never a replacement.
+ *
+ * A missing or unparseable header is NOT a refusal: chunked requests omit it
+ * legitimately, and refusing them would break a correct client to catch a
+ * dishonest one.
+ */
+export function refuseOversizedBody(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    const declared = Number(c.req.header('content-length'));
+    if (!Number.isFinite(declared) || declared <= maxBytes)
+        return null;
+    return {
+        status: 413,
+        error: `${label} too large (${declared} bytes; the limit is ${maxBytes})`,
+    };
+}
+/**
+ * Read a JSON body, refusing anything over `maxBytes` before parsing it.
+ *
+ * The size is measured in BYTES, not characters. `String.length` counts UTF-16
+ * code units, so a body of 4-byte emoji measures half its true size that way —
+ * which would let a caller past a byte limit the proxy is enforcing in real
+ * bytes, and produce the mismatch this module exists to close.
+ */
+export async function readBoundedJson(c, options) {
+    const { maxBytes, label = 'body' } = options;
+    let raw;
+    try {
+        raw = await c.req.text();
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} could not be read` };
+    }
+    const bytes = new TextEncoder().encode(raw).length;
+    if (bytes > maxBytes) {
+        return {
+            ok: false,
+            status: 413,
+            error: `${label} too large (${bytes} bytes; the limit is ${maxBytes})`,
+        };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, status: 400, error: `${label} must be JSON` };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.1.0",
+	"version": "4.3.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -66,6 +66,12 @@
 			"source": "./src/server/storage/binaryStoreFake.ts",
 			"import": "./dist/server/storage/binaryStoreFake.js"
 		},
+		"./body-limit": {
+			"types": "./dist/server/middleware/bodyLimit.d.ts",
+			"bun": "./src/server/middleware/bodyLimit.ts",
+			"source": "./src/server/middleware/bodyLimit.ts",
+			"import": "./dist/server/middleware/bodyLimit.js"
+		},
 		"./d1": {
 			"types": "./dist/server/d1/index.d.ts",
 			"bun": "./src/server/d1/index.ts",
@@ -252,7 +258,7 @@
 		"@node-rs/argon2": "^2.0.2",
 		"@types/bun": "^1.3.14",
 		"@types/node": "^24",
-		"cursedbelt": "^3.0.0",
+		"cursedbelt": "^4.1.1",
 		"hono": "4.12.28",
 		"kysely": "^0.28.17",
 		"kysely-bun-sqlite": "^0.4.0",

package/src/leafSubpathsImportNothing.spec.ts

@@ -138,6 +138,19 @@ const LEAVES = [
      */
     evaluates: 'binaryStoreFakeDefaults',
   },
+  {
+    subpath: './body-limit',
+    /**
+     * 🔴 The last line of defense on an oversized request body, and the leaf with the
+     * strictest promise of the lot: it imports NOTHING — not `hono`, not the error
+     * envelope, not a sibling in `src/server/middleware/`. It takes its request as a
+     * structural `{ req: { text() } }` source precisely so that neither a consumer nor a
+     * test needs a framework, which is what made it an ADDITION rather than a port when it
+     * arrived in 4.2.0 from five byte-identical app-side copies. Reaching it through the
+     * `./middleware` barrel would undo all of that in one import.
+     */
+    evaluates: 'readBoundedJson',
+  },
 ] as const;
 
 /**

package/src/server/bench/assert.ts

@@ -19,7 +19,11 @@ export type CpuViolationKind =
   /** An exempt route crossed its own `noticeAboveMs`. Never fails a build. */
   | 'exempt-notice'
   /** The clock could not measure at all. */
-  | 'unmeasurable';
+  | 'unmeasurable'
+  /** The clock claimed to work and the report holds no route at all. */
+  | 'no-samples'
+  /** Every reading on every route was exactly zero — a reader that is not reading. */
+  | 'degenerate';
 
 export interface CpuViolation {
   kind: CpuViolationKind;
@@ -48,10 +52,19 @@ export interface AssertCpuBudgetsOpts {
    */
   requireDeclared?: boolean;
   /**
-   * Treat an unavailable clock as a pass. Off by default — a gate that goes green
-   * because it measured nothing is worse than no gate.
+   * Treat an unavailable clock — or a report holding no route at all — as a pass. Off by
+   * default: a gate that goes green because it measured nothing is worse than no gate.
    */
   allowUnmeasurable?: boolean;
+  /**
+   * Accept a report in which every reading on every route was exactly zero. Off by
+   * default.
+   *
+   * 🔴 The only reason to turn this on is a runtime whose CPU reader has whole-millisecond
+   * resolution and an app genuinely below it — and then the budget is not measuring
+   * anything either. Prefer a finer reader.
+   */
+  allowZeroCpu?: boolean;
 }
 
 const fmt = (n: number): string => (Number.isFinite(n) ? n.toFixed(2) : 'n/a');
@@ -82,6 +95,68 @@ export function checkCpuBudgets(
     ];
   }
 
+  // 🔴 A report with no route in it is a wiring failure wearing a pass. The loop below
+  // runs zero times and returns zero violations, so `cpuBudget()` left unmounted, a bench
+  // whose cases never reached the middleware, or a reader returning a non-number (every
+  // sample dropped as unmeasurable by `createCpuRecorder`) all assert GREEN. Measured
+  // 2026-09-17 against this file before this guard existed: all three did.
+  if (report.available && report.routes.length === 0 && !opts.allowUnmeasurable) {
+    return [
+      {
+        kind: 'no-samples',
+        key: '*',
+        method: '*',
+        route: '*',
+        p99: Number.NaN,
+        budgetMs: null,
+        samples: 0,
+        fails: true,
+        message:
+          `CPU budget: clock source '${report.source}' reported itself available but not ` +
+          'one route was recorded. Nothing was measured, so nothing was proven: check ' +
+          'that cpuBudget() is mounted on the app under test, that the bench cases reach ' +
+          'it, and that the CPU reader returns a finite number.',
+      },
+    ];
+  }
+
+  // 🔴 A reader that answers the same number every time is the failure `cpuClock.ts`'s
+  // header names: "a clock that reads zero for ever and a gate that can never go red".
+  // It is the more dangerous shape of the two above, because `workerCpuClock` stamps it
+  // `proxy: false` — so the report claims to be the real quantity Cloudflare bills while
+  // every route sits at 0.00 and every budget passes. Requiring EVERY route to be totally
+  // flat keeps this off a real measurement: one non-zero reading anywhere clears it.
+  const totalSamples = report.routes.reduce((n, r) => n + r.samples, 0);
+  const allFlatZero = report.routes.every(
+    (r) => r.retained > 0 && r.max === 0 && r.totalCpuMs === 0,
+  );
+  if (
+    report.available &&
+    report.routes.length > 0 &&
+    totalSamples >= minSamples &&
+    allFlatZero &&
+    !opts.allowZeroCpu
+  ) {
+    return [
+      {
+        kind: 'degenerate',
+        key: '*',
+        method: '*',
+        route: '*',
+        p99: 0,
+        budgetMs: null,
+        samples: totalSamples,
+        fails: true,
+        message:
+          `CPU budget: every one of ${totalSamples} sample(s) across ` +
+          `${report.routes.length} route(s) read exactly 0 CPU-ms from source ` +
+          `'${report.source}'${report.proxy ? '' : ' (reported as NON-proxy)'}. A reader ` +
+          'that never moves cannot ever redden this gate. Wire a real CPU reader, or set ' +
+          'allowZeroCpu deliberately.',
+      },
+    ];
+  }
+
   for (const r of report.routes) {
     const base: Omit<CpuViolation, 'kind' | 'message' | 'fails'> = {
       key: r.key,

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

@@ -3,6 +3,7 @@ import {
   DAYS_PER_MONTH,
   DEFAULT_ROUTE_CPU_BUDGET_MS,
   deriveCpuBudgetMs,
+  MEASURED_FLEET_REQUESTS_PER_DAY,
   monthlyOverageUsd,
   OWNER_PROJECTED_REQUESTS_PER_DAY,
   resolveBudget,
@@ -35,6 +36,32 @@ describe('the derivation', () => {
   it('refuses a zero/negative request volume rather than returning Infinity', () => {
     expect(() => deriveCpuBudgetMs({ requestsPerMonth: 0 })).toThrow(/must be > 0/);
   });
+
+  it('re-derives ~22.9 CPU-ms from the MEASURED fleet volume, not the projection', () => {
+    // The outcome asked for the 9.9 to be re-derived from real traffic. It was, on
+    // 2026-09-16: six apps' `request_metrics` tables sum to 42,971/day, which is 43 %
+    // of the owner's 100,000/day guess — so the allowance is 2.3× wider than shipped.
+    expect(MEASURED_FLEET_REQUESTS_PER_DAY / OWNER_PROJECTED_REQUESTS_PER_DAY).toBeCloseTo(
+      0.43,
+      2,
+    );
+    const measured = deriveCpuBudgetMs({ requestsPerDay: MEASURED_FLEET_REQUESTS_PER_DAY });
+    expect(measured).toBeCloseTo(22.9, 1);
+    // And the measured volume is well inside the included REQUEST allowance, which is
+    // the whole reason CPU — not requests — is the budget worth gating on.
+    expect((MEASURED_FLEET_REQUESTS_PER_DAY * DAYS_PER_MONTH) / 10_000_000).toBeLessThan(0.2);
+  });
+
+  it('🔴 keeps the shipped default STRICTER than the measured allowance', () => {
+    // This is the guard, not the paragraph. The measured corpus is the RETIRED
+    // generation's — every table stops within hours of its app's graduation and no app
+    // is on a Worker yet — so raising the default to 22.9 would loosen every budget in
+    // the fleet on evidence that cannot carry it. Being 2.3× conservative costs nothing;
+    // being 2.3× loose costs the thing this module exists to prevent. If someone later
+    // drifts the default above what the traffic can justify, this goes red.
+    const measured = deriveCpuBudgetMs({ requestsPerDay: MEASURED_FLEET_REQUESTS_PER_DAY });
+    expect(DEFAULT_ROUTE_CPU_BUDGET_MS).toBeLessThanOrEqual(measured);
+  });
 });
 
 describe('what going over actually costs', () => {