cursedbelt-server 4.1.0 → 4.3.0

package/src/server/d1/invocation.ts

@@ -0,0 +1,207 @@
+/**
+ * The per-invocation query budget — D1's 1,000-queries-per-Worker-invocation cap, counted.
+ *
+ * ## 🔴 Why this file exists: the limit the rest of the seam only documented
+ *
+ * `./limits` lists `queriesPerInvocation: 1_000` FIRST, and its header names the exact
+ * failure — *"An N+1 loop over `family`'s 489 people exceeds it. Join, or `batch()`; do not
+ * loop."* Measured here 2026-09-18, that limit was the one thing in the table nothing
+ * enforced: `assertBatchSize` checks the length of a SINGLE `batch()` call, so a loop
+ * issuing 1,001 separate `await db.prepare(…).run()` calls passed every check in the seam.
+ * Each statement is under 100 parameters, each batch is under 1,000 members, and the
+ * invocation still dies in production.
+ *
+ * That is the seam's own defining defect wearing a third costume. Sync-locally and
+ * lenient-locally are both "green on this Mac, red in the Worker"; so is uncounted-locally,
+ * because `bun:sqlite` has no such cap and never will. The N+1 loop is also the single most
+ * likely shape to appear during a port — it is what the un-ported synchronous code already
+ * looks like, and awaiting it in a `for` loop is the laziest mechanical translation.
+ *
+ * ## The counter belongs to a REQUEST, not to a handle
+ *
+ * D1's cap is per Worker invocation, and a `D1LikeDatabase` is not an invocation: on a
+ * Worker it happens to be built per request, but locally `createLocalD1` is built once per
+ * PROCESS and lives for days. A counter on the handle would therefore be correct remotely
+ * and a false positive locally after the 1,000th query of the morning — the mirror image of
+ * the bug this seam exists to prevent, and just as fatal to the rule's credibility.
+ *
+ * So the scope is explicit and cheap, and the caller opens one per request:
+ *
+ * ```ts
+ * export default {
+ *   async fetch(req: Request, env: Env) {
+ *     const db = perInvocation(createRemoteD1(env.DB));
+ *     return handle(req, db);            // 1,001st query throws, naming the loop
+ *   },
+ * };
+ * ```
+ *
+ * It wraps either driver, because it sits ABOVE the seam and only counts. That is what
+ * makes the local gate able to prove a production-only limit: wrap a local database in a
+ * test, run the loop, and the laptop fails exactly where the Worker would.
+ */
+
+import { LIMITS } from './limits';
+import { D1LimitError, type D1LikeBindable, type D1LikeDatabase, type D1LikeResult, type D1LikeRow, type D1LikeStatement, type D1LikeValue } from './types';
+
+/**
+ * A database handle that knows how much of its invocation budget it has spent.
+ *
+ * `used` counts QUERIES the way D1 bills them: one per terminal statement call
+ * (`first`/`all`/`run`/`raw`), one per member of a `batch()`, and one per statement an
+ * `exec()` ran. Building a statement with `prepare()` or `bind()` costs nothing, because it
+ * reaches the database only when it is executed.
+ */
+export interface InvocationD1 extends D1LikeDatabase {
+	/** Queries charged to this invocation so far. */
+	readonly used: number;
+	/** Queries left before the cap, floored at 0. */
+	readonly remaining: number;
+}
+
+/**
+ * The statements a wrapper handed out, mapped back to the driver's own.
+ *
+ * 🔴 Both drivers identify their own statements structurally — `local.ts` probes for
+ * `allSync`, `remote.ts` for `binding` — and refuse anything else with "a local statement
+ * cannot run inside a D1 batch". A counted wrapper has neither property, so passing the
+ * wrappers straight through would break `batch()` on BOTH sides. `batch()` therefore
+ * unwraps here before delegating. A statement this does not know is passed through
+ * untouched, so the driver's own error is what a genuine cross-driver mix-up still gets.
+ */
+const INNER = new WeakMap<D1LikeStatement, D1LikeStatement>();
+
+class Budget {
+	used = 0;
+
+	constructor(readonly max: number) {}
+
+	/** Charge before the work goes out, so the query over the cap is never issued. */
+	charge(n: number, what: string): void {
+		if (this.used + n > this.max) {
+			throw new D1LimitError(
+				'queries per Worker invocation',
+				this.used + n,
+				this.max,
+				`${what} would be query ${this.used + n} of this invocation. This is almost always an N+1 loop — ` +
+					'replace the loop with a JOIN, or collect the statements and send them as one `batch()`. ' +
+					'Work that genuinely needs more than a thousand queries belongs in a Queue consumer or a Cron Trigger, ' +
+					'which get a fresh budget per invocation.',
+			);
+		}
+		this.used += n;
+	}
+
+	/**
+	 * Record a cost that was only knowable after the fact — see `exec()` below. Deliberately
+	 * unchecked: the statements have already run, so throwing here would report a limit
+	 * breach by hiding the result that proves it. Going over simply means the next
+	 * {@link charge} throws, which is the first moment a refusal can still prevent anything.
+	 */
+	settle(n: number): void {
+		this.used += n;
+	}
+}
+
+/** Wrap one statement so every terminal call is charged to `budget`. */
+function countedStatement(inner: D1LikeStatement, budget: Budget, sql: string): D1LikeStatement {
+	const label = `\`${sql.trim().slice(0, 60)}\``;
+
+	class CountedStatement implements D1LikeStatement {
+		bind(...values: D1LikeBindable[]): D1LikeStatement {
+			// Binding is free — it reaches nothing. The NEW statement is wrapped too, or a
+			// `prepare().bind().run()` would escape the count entirely.
+			return countedStatement(inner.bind(...values), budget, sql);
+		}
+
+		async first<T = D1LikeRow>(column?: string): Promise<T | null> {
+			budget.charge(1, label);
+			return column === undefined ? inner.first<T>() : (inner.first<T>(column) as Promise<T | null>);
+		}
+
+		async all<T = D1LikeRow>(): Promise<D1LikeResult<T>> {
+			budget.charge(1, label);
+			return inner.all<T>();
+		}
+
+		async run(): Promise<D1LikeResult<never>> {
+			budget.charge(1, label);
+			return inner.run();
+		}
+
+		async raw<V = D1LikeValue>(): Promise<V[][]> {
+			budget.charge(1, label);
+			return inner.raw<V>();
+		}
+	}
+
+	const wrapped = new CountedStatement();
+	INNER.set(wrapped, inner);
+	return wrapped;
+}
+
+/**
+ * Give `db` a query budget for ONE Worker invocation.
+ *
+ * Construct a fresh one per request — the count is the request's, not the handle's, and
+ * re-using one across requests would refuse the 1,001st query of the day rather than of the
+ * invocation. See the header for why that distinction is the whole design.
+ *
+ * `max` exists for tests and for a caller that wants to be refused sooner than D1 would
+ * (a route with a budget of 50 finds its own N+1 long before the hard cap does). It may not
+ * be raised above D1's real limit, because a budget larger than the service's is a number
+ * that reports success right up until production disagrees.
+ */
+export function perInvocation(db: D1LikeDatabase, opts: { max?: number } = {}): InvocationD1 {
+	const max = opts.max ?? LIMITS.queriesPerInvocation;
+	if (!Number.isInteger(max) || max < 1) {
+		throw new RangeError(`max must be a positive integer, got ${max}`);
+	}
+	if (max > LIMITS.queriesPerInvocation) {
+		throw new D1LimitError(
+			'queries per Worker invocation',
+			max,
+			LIMITS.queriesPerInvocation,
+			'A budget above D1\'s own cap cannot be honoured — the service refuses first. Lower it, or split the work across invocations.',
+		);
+	}
+	const budget = new Budget(max);
+
+	return {
+		flavor: db.flavor,
+
+		get used() {
+			return budget.used;
+		},
+
+		get remaining() {
+			return Math.max(0, budget.max - budget.used);
+		},
+
+		prepare(sql: string): D1LikeStatement {
+			return countedStatement(db.prepare(sql), budget, sql);
+		},
+
+		async batch<T = D1LikeRow>(statements: D1LikeStatement[]): Promise<D1LikeResult<T>[]> {
+			// One round trip, but D1 bills each member — so does this.
+			budget.charge(statements.length, `a batch() of ${statements.length}`);
+			return db.batch<T>(statements.map((s) => INNER.get(s) ?? s));
+		},
+
+		/**
+		 * 🔴 The one cost that cannot be charged up front. `exec()` runs however many
+		 * statements the SQL contains, and remotely that number comes back FROM the service —
+		 * there is nothing trustworthy to count beforehand. So this reserves one query, runs,
+		 * and settles the true cost afterwards; an `exec` that blows the budget is reported on
+		 * the next query rather than prevented. That is an acceptable trade only because
+		 * `exec` is the DDL/migration path — it carries no user input by contract, and it is
+		 * not the shape an N+1 loop takes.
+		 */
+		async exec(sql: string): Promise<{ count: number; duration: number }> {
+			budget.charge(1, 'an exec()');
+			const res = await db.exec(sql);
+			if (res.count > 1) budget.settle(res.count - 1);
+			return res;
+		},
+	};
+}

package/src/server/d1/local.ts

@@ -25,11 +25,22 @@ import {
 	type D1LikeValue,
 	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 = (): number => 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: Database): number =>
+	(db.query('SELECT total_changes() AS n').get() as { n: number }).n;
+
+/** The connection's last inserted rowid, which is what D1 reports in `meta.last_row_id`. */
+const lastInsertRowid = (db: Database): number =>
+	(db.query('SELECT last_insert_rowid() AS r').get() as { r: number }).r;
+
 /**
  * 🔴 The synchronous core, kept separate from the async surface on purpose.
  *
@@ -63,11 +74,53 @@ class LocalStatement implements D1LikeStatement, SyncExecutable {
 
 	allSync<T = D1LikeRow>(): D1LikeResult<T> {
 		const started = now();
-		const rows = this.stmt().all(...(this.params as never[])) as Record<string, unknown>[];
+		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 as never[]));
+			return {
+				results: [],
+				success: true,
+				meta: makeMeta({
+					changes: res.changes,
+					last_row_id: res.lastInsertRowid,
+					duration: now() - started,
+				}),
+			};
+		}
+
+		const rowsOf = () => this.stmt().all(...(this.params as never[])) as Record<string, unknown>[];
+
+		// 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<T>(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<T>(rows),
 			success: true,
-			meta: makeMeta({ duration: now() - started }),
+			meta: makeMeta({
+				changes,
+				last_row_id: changes > 0 ? lastInsertRowid(this.db) : null,
+				duration: now() - started,
+			}),
 		};
 	}
 

package/src/server/d1/sameShape.spec.ts

@@ -276,4 +276,77 @@ describe('local and D1 drivers return identical shapes', () => {
 		expect(await attempt(p.local)).toBe(0);
 		expect(await attempt(p.remote)).toBe(0);
 	});
+
+	// ── batch META, which both sides got wrong the same way until 2026-09-17 ──────────
+	//
+	// 🔴 These four assert VALUES, not just agreement. The bug they pin was `changes: 0`
+	// hardcoded in `local.ts`'s `allSync` AND in `fakeD1`'s `batch`, so the two drivers
+	// agreed perfectly on a wrong answer and every `expect(local).toEqual(remote)` above
+	// stayed green. A shared bug is the one failure mode a two-implementation test cannot
+	// see, so the numbers have to be written down here. Found by porting
+	// `apps/patterns/src/server/tokens.ts` onto the seam, on its first atomic write.
+
+	test('batch() reports each member’s OWN changes — not zero, on both', async () => {
+		p.seed(`INSERT INTO t (id, text_col) VALUES (1, 'a'), (2, 'b'), (3, 'c')`);
+		const { local, remote } = await both(p, async (db) => {
+			const res = await db.batch([
+				db.prepare("UPDATE t SET text_col = 'z'"),
+				db.prepare('DELETE FROM t WHERE id = ?').bind(1),
+			]);
+			return res.map((r) => r.meta.changes);
+		});
+		expect(local).toEqual(remote);
+		// The whole point: three rows updated and one deleted, reported per statement.
+		expect(local).toEqual([3, 1]);
+	});
+
+	test('batch() reports last_row_id for an insert, on both', async () => {
+		const { local, remote } = await both(p, async (db) => {
+			const res = await db.batch([
+				db.prepare('INSERT INTO t (id, text_col) VALUES (41, ?)').bind('a'),
+				db.prepare('INSERT INTO t (id, text_col) VALUES (42, ?)').bind('b'),
+			]);
+			return res.map((r) => ({ changes: r.meta.changes, last_row_id: r.meta.last_row_id }));
+		});
+		expect(local).toEqual(remote);
+		expect(local).toEqual([
+			{ changes: 1, last_row_id: 41 },
+			{ changes: 1, last_row_id: 42 },
+		]);
+	});
+
+	test('a READ inside a batch reports changes 0, even right after a write', async () => {
+		// 🔴 The trap in the obvious fix. SQLite's `changes()` is connection-wide and
+		// sticky, so a driver that simply reads it after every statement reports the
+		// UPDATE's 3 as the SELECT's own count. Measured 2026-09-17: a `SELECT` following
+		// a one-row insert still answers `changes() = 1`.
+		p.seed(`INSERT INTO t (id, text_col) VALUES (1, 'a'), (2, 'b'), (3, 'c')`);
+		const { local, remote } = await both(p, async (db) => {
+			const res = await db.batch([
+				db.prepare("UPDATE t SET text_col = 'z'"),
+				db.prepare('SELECT id FROM t ORDER BY id'),
+			]);
+			return {
+				changes: res.map((r) => r.meta.changes),
+				rows: res[1]?.results,
+			};
+		});
+		expect(local).toEqual(remote);
+		expect(local.changes).toEqual([3, 0]);
+		expect(local.rows).toEqual([{ id: 1 }, { id: 2 }, { id: 3 }]);
+	});
+
+	test('INSERT … RETURNING in a batch reports its rows AND its changes, on both', async () => {
+		// Returns rows and writes, so neither the `.run()` path nor the pure-read path
+		// answers it — this is the case `total_changes()` differencing exists for.
+		const { local, remote } = await both(p, async (db) => {
+			const res = await db.batch([
+				db.prepare('INSERT INTO t (id, text_col) VALUES (7, ?), (8, ?) RETURNING id').bind('a', 'b'),
+			]);
+			return { rows: res[0]?.results, changes: res[0]?.meta.changes };
+		});
+		expect(local).toEqual(remote);
+		expect(local.changes).toBe(2);
+		expect(local.rows).toEqual([{ id: 7 }, { id: 8 }]);
+	});
 });

package/src/server/d1/values.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,
@@ -81,6 +81,27 @@ export function normalizeBind(value: unknown, index: number): D1LikeBindable {
 export const normalizeBinds = (values: readonly unknown[]): D1LikeBindable[] =>
 	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: string): boolean => /^select\b/i.test(sql.replace(LEADING_NOISE, ''));
+
 /**
  * Normalize one column value coming BACK from a driver.
  *

package/src/server/middleware/bodyLimit.spec.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  type BodyBytesSource,
+  type BodyHeaderSource,
+  type BodyTextSource,
+  readBoundedBytes,
+  readBoundedJson,
+  readBoundedText,
+  refuseOversizedBody,
+} from './bodyLimit';
+
+/**
+ * 🔴 A guard that is the LAST line of defense ships with the test of its failure path,
+ * not only of its success path.
+ *
+ * `apps/roms/src/server/limits.test.ts` is where this came from (2026-09-17). Most of
+ * that file is about roms' own `routes.ts` — that every bounded-body call site takes its
+ * ceiling from `MAX_BODY_BYTES` — and stays there, because it asserts about an app's
+ * routes. What travels with the module is its two behavioural tests (an honest oversized
+ * declaration is refused with both numbers in the message; a body with no declared length
+ * is NOT refused on that ground alone), extended here to the three readers the app-side
+ * file never exercised.
+ *
+ * Every source below is a plain object literal. That is the module's design showing
+ * through rather than a shortcut: the four entry points take structural
+ * `{ req: { … } }` sources, so nothing here needs Hono, a server, or a socket — which is
+ * also why `cursedbelt-server/body-limit` can promise to import nothing at runtime.
+ */
+
+const textSource = (raw: string): BodyTextSource => ({ req: { text: async () => raw } });
+
+const bytesSource = (bytes: Uint8Array): BodyBytesSource => ({
+  req: {
+    async arrayBuffer() {
+      return bytes.buffer.slice(
+        bytes.byteOffset,
+        bytes.byteOffset + bytes.byteLength,
+      ) as ArrayBuffer;
+    },
+  },
+});
+
+/** A body that dies mid-read — a client that hung up, a socket reset. */
+const brokenText: BodyTextSource = {
+  req: {
+    text: async () => {
+      throw new Error('connection reset');
+    },
+  },
+};
+
+const brokenBytes: BodyBytesSource = {
+  req: {
+    arrayBuffer: async () => {
+      throw new Error('connection reset');
+    },
+  },
+};
+
+const headerSource = (contentLength: string | undefined): BodyHeaderSource => ({
+  req: { header: (name) => (name === 'content-length' ? contentLength : undefined) },
+});
+
+describe('readBoundedJson', () => {
+  it('parses a body inside the ceiling', async () => {
+    const result = await readBoundedJson<{ hello: string }>(
+      textSource('{"hello":"world"}'),
+      { maxBytes: 1024 },
+    );
+    expect(result.ok).toBe(true);
+    expect(result.ok === true ? result.value : null).toEqual({ hello: 'world' });
+  });
+
+  it('refuses an oversized body with 413 and BOTH numbers in the message', async () => {
+    const raw = JSON.stringify({ blob: 'x'.repeat(200) });
+    const result = await readBoundedJson(textSource(raw), {
+      maxBytes: 64,
+      label: 'save state',
+    });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.status : 0).toBe(413);
+    const error = result.ok === false ? result.error : '';
+    expect(error).toContain('save state');
+    expect(error).toContain(String(raw.length)); // what arrived
+    expect(error).toContain('64'); // what was allowed
+  });
+
+  /**
+   * 🔴 The reason the module measures `TextEncoder().encode(raw).length` and not
+   * `raw.length`. A 4-byte emoji is 2 UTF-16 code units, so a `String.length` check
+   * measures this body at 8 against a real size of 14 — and lets it past a byte limit
+   * the proxy in front is enforcing in real bytes. That mismatch is what this module
+   * exists to close, so it gets an assertion rather than a sentence.
+   */
+  it('measures BYTES, not UTF-16 code units', async () => {
+    const raw = JSON.stringify('😀😀😀');
+    expect(raw.length).toBe(8);
+    expect(new TextEncoder().encode(raw).length).toBe(14);
+    const result = await readBoundedJson(textSource(raw), { maxBytes: 10 });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.status : 0).toBe(413);
+  });
+
+  it('allows a body exactly ON the ceiling — the limit is inclusive', async () => {
+    const raw = '"abcd"'; // 6 bytes
+    const result = await readBoundedJson(textSource(raw), { maxBytes: 6 });
+    expect(result.ok).toBe(true);
+  });
+
+  /** A 400, never a throw: the caller gets a status to return, not an exception to catch. */
+  it('answers 400 for a body that is not JSON', async () => {
+    const result = await readBoundedJson(textSource('not json at all'), {
+      maxBytes: 1024,
+      label: 'preferences',
+    });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.status : 0).toBe(400);
+    expect(result.ok === false ? result.error : '').toBe('preferences must be JSON');
+  });
+
+  it('answers 400 when the body cannot be read at all', async () => {
+    const result = await readBoundedJson(brokenText, { maxBytes: 1024 });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.status : 0).toBe(400);
+    expect(result.ok === false ? result.error : '').toBe('body could not be read');
+  });
+});
+
+describe('readBoundedText', () => {
+  it('hands back the raw text inside the ceiling', async () => {
+    const result = await readBoundedText(textSource('chunk-payload'), { maxBytes: 64 });
+    expect(result.ok).toBe(true);
+    expect(result.ok === true ? result.value : '').toBe('chunk-payload');
+  });
+
+  it('refuses an oversized body with 413, measured in bytes', async () => {
+    const result = await readBoundedText(textSource('😀'.repeat(4)), {
+      maxBytes: 8,
+      label: 'chunk',
+    });
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.status : 0).toBe(413);
+    expect(result.ok === false ? result.error : '').toContain('chunk too large (16 bytes');
+  });
+
+  it('answers 400 when the body cannot be read', async () => {
+    const result = await readBoundedText(brokenText, { maxBytes: 64 });
+    expect(result.ok === false ? result.status : 0).toBe(400);
+  });
+});
+
+describe('readBoundedBytes', () => {
+  it('hands back the exact bytes inside the ceiling', async () => {
+    const payload = new Uint8Array([0x00, 0xff, 0x80, 0x41]);
+    const result = await readBoundedBytes(bytesSource(payload), { maxBytes: 16 });
+    expect(result.ok).toBe(true);
+    expect([...(result.ok === true ? result.value : [])]).toEqual([0x00, 0xff, 0x80, 0x41]);
+  });
+
+  /**
+   * The reason this exists beside {@link readBoundedText}: 0x80 and 0xff are not valid
+   * UTF-8, so decoding cartridge bytes as text would replace them with U+FFFD and measure
+   * a size that is not the size the proxy is enforcing.
+   */
+  it('does not corrupt bytes that are invalid UTF-8', async () => {
+    const payload = new Uint8Array([0x80, 0xfe, 0xff]);
+    const result = await readBoundedBytes(bytesSource(payload), { maxBytes: 16 });
+    expect(result.ok === true ? result.value.length : -1).toBe(3);
+    expect(new TextDecoder().decode(result.ok === true ? result.value : new Uint8Array())).toBe(
+      '���',
+    );
+  });
+
+  it('refuses an oversized buffer with 413 and both numbers', async () => {
+    const result = await readBoundedBytes(bytesSource(new Uint8Array(100)), {
+      maxBytes: 32,
+      label: 'rom chunk',
+    });
+    expect(result.ok === false ? result.status : 0).toBe(413);
+    expect(result.ok === false ? result.error : '').toBe(
+      'rom chunk too large (100 bytes; the limit is 32)',
+    );
+  });
+
+  it('answers 400 when the body cannot be read', async () => {
+    const result = await readBoundedBytes(brokenBytes, { maxBytes: 32 });
+    expect(result.ok === false ? result.status : 0).toBe(400);
+  });
+});
+
+describe('refuseOversizedBody', () => {
+  /** The guard itself: an honest oversized declaration is refused, and the message names
+   *  both numbers so a 413 is actionable rather than mysterious. */
+  it('refuses an oversized declared body with both numbers in the message', () => {
+    const refusal = refuseOversizedBody(headerSource('4194305'), {
+      maxBytes: 4 * 1024 * 1024,
+      label: 'save state',
+    });
+    expect(refusal?.status).toBe(413);
+    expect(refusal?.error).toContain('save state');
+    expect(refusal?.error).toContain('4194305');
+    expect(refusal?.error).toContain('4194304');
+  });
+
+  /**
+   * A chunked request legitimately omits `Content-Length`. Refusing it would break a
+   * correct client to catch a dishonest one — and the dishonest one is caught by the
+   * buffering readers anyway, which measure what actually arrived.
+   */
+  it('does not refuse a body with no declared length on that ground alone', () => {
+    expect(refuseOversizedBody(headerSource(undefined), { maxBytes: 1024 })).toBeNull();
+  });
+
+  it('does not refuse an unparseable declared length', () => {
+    expect(refuseOversizedBody(headerSource('not-a-number'), { maxBytes: 1024 })).toBeNull();
+  });
+
+  it('does not refuse a body exactly on the ceiling', () => {
+    expect(refuseOversizedBody(headerSource('1024'), { maxBytes: 1024 })).toBeNull();
+  });
+
+  /**
+   * 🔴 The compensating control, asserted rather than described. This function TRUSTS the
+   * header — it has to, because a `multipart/form-data` body cannot be measured without
+   * buffering it first, which is the thing the limit exists to prevent. What makes that
+   * safe is that a liar only gets as far as the next guard: a body declaring 1 byte and
+   * carrying 5 MB is still refused by the reader that measures what arrived.
+   */
+  it('is bypassed by a lying header — and the buffering reader still refuses', async () => {
+    const liar = headerSource('1');
+    expect(refuseOversizedBody(liar, { maxBytes: 1024 })).toBeNull();
+
+    const actuallyHuge = await readBoundedBytes(bytesSource(new Uint8Array(5000)), {
+      maxBytes: 1024,
+    });
+    expect(actuallyHuge.ok === false ? actuallyHuge.status : 0).toBe(413);
+  });
+});