cursedbelt-server 4.1.0 → 4.2.0

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.2.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",

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/cpuBudget.spec.ts

@@ -3,7 +3,12 @@ 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 {
+  fixedCpuClock,
+  processCpuClock,
+  unavailableCpuClock,
+  workerCpuClock,
+} from './cpuClock';
 import { createCpuRecorder } from './recorder';
 import { runCpuBench } from './runBench';
 
@@ -300,3 +305,98 @@ describe('the bench runner', () => {
     await expect(runCpuBench({ app, recorder, cases: [] })).rejects.toThrow(/no cases/);
   });
 });
+
+/**
+ * 🔴 **The third direction: a gate that CANNOT go red.**
+ *
+ * The two directions above prove the assertion fires on a real over-budget route and stays
+ * quiet on a real under-budget one. Both assume the report describes something that was
+ * measured. Measured 2026-09-17, before the guards these cases cover: an empty report, a
+ * constant-zero `workerCpuClock`, and a reader returning `undefined` ALL asserted green —
+ * and the middle one did it carrying `proxy: false`, the exact flag that says "quote this
+ * as a Cloudflare billing fact".
+ *
+ * `cpuClock.ts`'s own header predicted it — *"a clock that reads zero for ever and a gate
+ * that can never go red"* — so this block is that paragraph turned into checks.
+ */
+describe('direction 3 — a gate that measured nothing must FAIL, not pass', () => {
+  it('fails an available clock that recorded no route at all', () => {
+    const recorder = createCpuRecorder({ clock: processCpuClock() });
+    const report = recorder.report();
+    expect(report.available).toBe(true);
+    expect(report.routes).toHaveLength(0);
+
+    expect(() => assertCpuBudgets(report)).toThrow(/not one route was recorded/);
+    // requireDeclared must not be what saves it — it has no routes to require anything of.
+    expect(() => assertCpuBudgets(report, { requireDeclared: true })).toThrow(/no-samples|not one route/);
+    // The one deliberate escape hatch.
+    expect(assertCpuBudgets(report, { allowUnmeasurable: true })).toEqual([]);
+  });
+
+  it('fails a bench whose app never mounted cpuBudget() — the real wiring mistake', async () => {
+    const recorder = createCpuRecorder({ clock: processCpuClock() });
+    const app = new Hono(); // 🔴 no app.use('*', cpuBudget({ recorder }))
+    app.get('/api/cheap', (c) => c.json({ ok: true }));
+
+    // The bench itself is happy: every case returns 200.
+    const report = await runCpuBench({ app, recorder, cases: [{ path: '/api/cheap' }] });
+    expect(report.routes).toHaveLength(0);
+    expect(() => assertCpuBudgets(report)).toThrow(/cpuBudget\(\) is mounted/);
+  });
+
+  it('fails a constant-zero worker reader, and says it was reported as NON-proxy', () => {
+    const clock = workerCpuClock(() => 0);
+    const recorder = createCpuRecorder({ clock });
+    for (let i = 0; i < 40; i += 1) recorder.record('GET', '/api/thing', clock.start()());
+
+    const report = recorder.report();
+    // This is the shape that makes it dangerous: it claims to be billable truth.
+    expect(report.proxy).toBe(false);
+    expect(report.routes[0].samples).toBe(40);
+    expect(report.routes[0].p99).toBe(0);
+
+    expect(() => assertCpuBudgets(report)).toThrow(/never moves cannot ever redden/);
+    expect(() => assertCpuBudgets(report)).toThrow(/NON-proxy/);
+    expect(assertCpuBudgets(report, { allowZeroCpu: true })).toEqual([]);
+  });
+
+  it('does NOT fire when any route read a real number — one non-zero clears it', () => {
+    const recorder = createCpuRecorder({ clock: fixedCpuClock([0]) });
+    for (let i = 0; i < 40; i += 1) recorder.record('GET', '/api/flat', 0);
+    recorder.record('GET', '/api/real', 0.25);
+
+    const violations = checkCpuBudgets(recorder.report(), { minSamples: 1 });
+    expect(violations.map((v) => v.kind)).not.toContain('degenerate');
+  });
+
+  it('refuses a reader that is not callable, at wiring time', () => {
+    expect(() => workerCpuClock(undefined as unknown as () => number)).toThrow(
+      /needs a function returning CPU-ms/,
+    );
+  });
+
+  it('treats a non-numeric reading as unmeasurable, never as zero', () => {
+    const clock = workerCpuClock(() => undefined as unknown as number);
+    expect(Number.isNaN(clock.start()())).toBe(true);
+
+    // NaN is dropped by the recorder, so the run lands on the no-samples guard rather
+    // than reporting a confident 0.00 for every route.
+    const recorder = createCpuRecorder({ clock });
+    for (let i = 0; i < 40; i += 1) recorder.record('GET', '/api/thing', clock.start()());
+    expect(() => assertCpuBudgets(recorder.report())).toThrow(/finite number/);
+  });
+
+  it('passes a worker clock that actually moves — the guards do not block a real one', () => {
+    let cpu = 0;
+    const clock = workerCpuClock(() => (cpu += 1.5), 'tail-worker cpuTime');
+    const recorder = createCpuRecorder({ clock, config: { routes: { 'GET /api/thing': 5 } } });
+    for (let i = 0; i < 40; i += 1) recorder.record('GET', '/api/thing', clock.start()());
+
+    const report = recorder.report();
+    expect(report.proxy).toBe(false);
+    expect(report.source).toBe('tail-worker cpuTime');
+    expect(report.routes[0].p99).toBeGreaterThan(0);
+    expect(assertCpuBudgets(report, { requireDeclared: true })).toEqual([]);
+    expect(formatCpuBudgetReport(report)).toContain('runtime-reported Worker CPU-ms');
+  });
+});

package/src/server/bench/cpuClock.ts

@@ -68,13 +68,34 @@ export function processCpuClock(): CpuClock {
  * @param readCpuMs Returns monotonically non-decreasing CPU-ms for the current invocation.
  */
 export function workerCpuClock(readCpuMs: () => number, source = 'worker-runtime'): CpuClock {
+  // This function is the only place `proxy: false` is stamped — the claim that a number may
+  // be quoted as a Cloudflare billing fact is made HERE, so it is checked here. A reader
+  // that is not callable can never be one, and finding that out at wiring time costs one
+  // cold start; finding it out later costs a gate that reads zero for ever.
+  if (typeof readCpuMs !== 'function') {
+    throw new TypeError(
+      'workerCpuClock: needs a function returning CPU-ms for the current invocation. ' +
+        'There is no built-in Cloudflare reader — the isolate does not hand a handler its ' +
+        'own CPU time, so this comes from a tail worker feeding cpuTime back.',
+    );
+  }
+  // 🔴 The reader is NOT called here. Cloudflare's CPU readings are request-scoped, so a
+  // correct reader may legitimately throw or read nothing at construction; validating
+  // eagerly would reject the very readers this exists to accept.
   return {
     source,
     proxy: false,
     available: true,
     start(): CpuSpan {
       const before = readCpuMs();
-      return () => Math.max(0, readCpuMs() - before);
+      return () => {
+        const after = readCpuMs();
+        // A non-numeric reading is unmeasurable, never zero. NaN is what
+        // `createCpuRecorder` drops as "not a sample"; a 0 would be recorded as a
+        // confident measurement of no work, which is the lie this module exists to avoid.
+        if (!Number.isFinite(before) || !Number.isFinite(after)) return Number.NaN;
+        return Math.max(0, after - before);
+      };
     },
   };
 }

package/src/server/d1/fakeD1.ts

@@ -19,6 +19,11 @@
  *      precision above 2^53 without a word.
  *   4. **Results are wrapped** in `{ results, success, meta }` rather than returned bare.
  *   5. **`BEGIN`/`COMMIT` is refused** — D1 has no interactive transaction.
+ *   6. **`batch()` reports each member's own `changes` / `last_row_id`**, because real D1
+ *      does. 🔴 Until 2026-09-17 this file hardcoded `changes: 0` there and so did the
+ *      local driver, so `sameShape.spec.ts` was green on a bug BOTH sides shared — the one
+ *      failure mode a two-implementation test cannot see. A real port of
+ *      `apps/patterns/src/server/tokens.ts` found it on its first atomic write.
  *
  * SQL semantics are real: it runs against an actual in-memory SQLite. Only the edges are
  * emulated, which are exactly the edges under test.
@@ -31,6 +36,7 @@
 
 import type { Database } from 'bun:sqlite';
 import type { D1BindingLike, D1BindingResult, D1BindingStatement } from './remote';
+import { isPureReadSql } from './values';
 
 /** The bind types a real D1 binding accepts. Everything else throws. */
 function assertD1Bindable(value: unknown, index: number): void {
@@ -135,8 +141,55 @@ class FakeD1Statement implements D1BindingStatement {
 		const rows = this.db.query(this.sql).values(...(this.params as never[])) as unknown[][];
 		return rows.map((r) => r.map(toWireValue));
 	}
+
+	/**
+	 * Execute synchronously and report the wire result, for `batch()`.
+	 *
+	 * 🔴 Synchronous on purpose: a `bun:sqlite` transaction callback may not await — a
+	 * promise resolved inside it settles a microtask after the transaction has already
+	 * committed. The local driver keeps a `SyncExecutable` for exactly this reason.
+	 *
+	 * The counters are read the same way real D1 populates `meta`, and deliberately NOT by
+	 * copying `local.ts`: this file is a divergence simulator, so it reaches its answer
+	 * independently and the shared-bug case stays detectable.
+	 */
+	runSync(): D1BindingResult {
+		assertRunnableOnD1(this.sql);
+		const started = performance.now();
+		const stmt = this.db.query(this.sql);
+		const bound = this.params as never[];
+
+		// No result columns → cannot return rows, and `.run()` is the only call that reports
+		// `changes`. This is the ordinary batch member: an INSERT, UPDATE or DELETE.
+		if (stmt.columnNames.length === 0) {
+			const res = stmt.run(...bound);
+			return { results: [], success: true, meta: this.meta(started, res.changes, Number(res.lastInsertRowid)) };
+		}
+
+		// A pure read wrote nothing. Its `changes()` would be the PREVIOUS statement's.
+		if (isPureReadSql(this.sql)) {
+			const rows = stmt.all(...bound) as Record<string, unknown>[];
+			return { results: rows.map(toWireRow), success: true, meta: this.meta(started, 0, 0) };
+		}
+
+		// Returns rows AND writes — `INSERT … RETURNING` and friends.
+		const before = totalChanges(this.db);
+		const rows = this.db.query(this.sql).all(...bound) as Record<string, unknown>[];
+		const changes = totalChanges(this.db) - before;
+		return {
+			results: rows.map(toWireRow),
+			success: true,
+			meta: this.meta(started, changes, changes > 0 ? lastInsertRowid(this.db) : 0),
+		};
+	}
 }
 
+/** Cumulative rows changed on this connection — a difference is one statement's count. */
+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 puts in `meta.last_row_id`. */
+const lastInsertRowid = (db: Database): number => (db.query('SELECT last_insert_rowid() AS r').get() as { r: number }).r;
+
 /**
  * Wrap a real `bun:sqlite` database in D1's API and D1's restrictions.
  *
@@ -154,26 +207,11 @@ export function createFakeD1Binding(db: Database): D1BindingLike {
 		async batch(statements: D1BindingStatement[]): Promise<D1BindingResult[]> {
 			// D1's batch is atomic — it is the only atomicity D1 offers. A real `bun:sqlite`
 			// transaction is the faithful local equivalent.
+			// 🔴 Each member reports its OWN `changes` / `last_row_id`, because real D1 does.
+			// This used to hardcode zero — see note 6 in the header for what that cost.
 			const results: D1BindingResult[] = [];
 			const run = db.transaction((stmts: D1BindingStatement[]) => {
-				for (const s of stmts) {
-					const started = performance.now();
-					const inner = s as FakeD1Statement;
-					assertRunnableOnD1(inner.sql);
-					const rows = db.query(inner.sql).all(...(inner.params as never[])) as Record<string, unknown>[];
-					results.push({
-						results: rows.map(toWireRow),
-						success: true,
-						meta: {
-							duration: performance.now() - started,
-							changes: 0,
-							last_row_id: 0,
-							rows_read: rows.length,
-							rows_written: 0,
-							served_by: 'fake-d1',
-						},
-					});
-				}
+				for (const s of stmts) results.push((s as FakeD1Statement).runSync());
 			});
 			run(statements);
 			return results;

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,
+			}),
 		};
 	}