cursedbelt-server 4.0.0 → 4.2.0

package/dist/server/storage/binaryStoreFake.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A `BinaryStore` that does nothing, so adding a method to the interface stops
+ * breaking twenty-two test files in apps nobody touched.
+ *
+ * ── The measurement (2026-09-08) ────────────────────────────────────────────
+ * `BinaryStore.fetchMedia` was added to serve audio off this Mac while
+ * Cloudflare's daily Worker quota was spent — a good change, landed on `main`,
+ * with apps/music green. It also broke **apps/collections and apps/roms**, four
+ * test files each, with `Property 'fetchMedia' is missing in type`. Both apps
+ * were left unable to typecheck, and therefore unable to gate or deploy, by a
+ * commit neither of them appears in. Nobody noticed for hours: a worker's
+ * `verify:scoped` only typechecks the workspaces its own diff touches, which is
+ * exactly the property that makes it fast.
+ *
+ * The owner's rule, in his words: *"a change to roms for example cannot block
+ * family tree app from passing its tests."* This is that rule for the one
+ * interface twenty-two suites all fake by hand.
+ *
+ * 🔴 **This is why the fake travels WITH the interface, into this package.** An
+ * interface whose change can break two other apps from a third app's commit is a
+ * shared interface already; a fake living in a different repo from the interface it
+ * fakes cannot do the job it exists for, because the two can be changed
+ * independently. Published as `cursedbelt-server/binary-store/testing`, beside
+ * `cursedbelt-server/binary-store` — the same split as `./d1` and `./d1/testing`, and
+ * for the same reason: a consumer's PRODUCTION graph must not be able to reach a
+ * fake.
+ *
+ * ── 🔴 Why defaults and not optional members ────────────────────────────────
+ * The obvious alternative is to mark each new capability `fetchMedia?:` on the
+ * interface. That moves the cost to every REAL consumer — each one then has to
+ * narrow before calling, for a method the production store always has — and it
+ * makes "did we implement this?" unanswerable by the typechecker, which is the
+ * one question the interface exists to answer. The fakes are the side that
+ * should absorb the change, so the defaults live here.
+ *
+ * ── What a default may do ───────────────────────────────────────────────────
+ * As little as possible, and never something a test could mistake for a result.
+ * `get` and `meta` answer "not here"; `fetchMedia` answers 404; the mutators do
+ * nothing. A suite that cares about any of them overrides it — spread this first
+ * and the file's own members win:
+ *
+ *     const store: BinaryStore = {
+ *       ...binaryStoreFakeDefaults("collections"),
+ *       async meta(key) { … what this suite is actually about … },
+ *     };
+ */
+import type { BinaryStore } from './binaryStore';
+/**
+ * Every member of {@link BinaryStore}, inert.
+ *
+ * @param appId the tenant the fake claims to be. Required, and deliberately so —
+ *        a blank tenant is the mistake `binaryStoreTenant` exists to catch, and a
+ *        fake that quietly defaults it would hide a test written against the
+ *        wrong app.
+ */
+export declare function binaryStoreFakeDefaults(appId: string): BinaryStore;

package/dist/server/storage/binaryStoreFake.js

@@ -0,0 +1,63 @@
+/**
+ * Every member of {@link BinaryStore}, inert.
+ *
+ * @param appId the tenant the fake claims to be. Required, and deliberately so —
+ *        a blank tenant is the mistake `binaryStoreTenant` exists to catch, and a
+ *        fake that quietly defaults it would hide a test written against the
+ *        wrong app.
+ */
+export function binaryStoreFakeDefaults(appId) {
+    return {
+        appId,
+        async put() { },
+        async putLarge() { },
+        async get() {
+            return null;
+        },
+        async meta() {
+            return null;
+        },
+        async stat() {
+            return null;
+        },
+        async has() {
+            return false;
+        },
+        // 🔴 `"unknown"`, never `"absent"`. A fake that claimed to know a key is missing
+        // would let a listing route's "answer only from the memo" branch look exercised
+        // when nothing was ever memoized — the one thing a test of that branch is for.
+        known() {
+            return 'unknown';
+        },
+        // 🔴 `0`, and never a lie about work done. The real one returns how many
+        // negative memos it dropped, and an app's repair route reports that number to
+        // the owner — a fake that invented one would make a broken repair read as a
+        // working one in the only test that could catch it.
+        forgetMisses() {
+            return 0;
+        },
+        cacheStats() {
+            return { present: 0, absent: 0 };
+        },
+        async remove() { },
+        async removePrefix() { },
+        async mediaUrl(key) {
+            // Carries the key, so an assertion on "which object was linked" reads.
+            return `https://binary-server.test/media/${appId}/${key}`;
+        },
+        async mediaPrefixUrl(prefix, master) {
+            // Carries BOTH, because the bug this shape exists to prevent is signing the wrong
+            // one of them — a URL pointing at the master but scoped to the wrong prefix 403s
+            // every segment while the master itself loads fine.
+            return `https://binary-server.test/media/${appId}/${master}?p=${encodeURIComponent(prefix)}`;
+        },
+        async fetchMedia() {
+            // 🔴 404, not an empty 200. A fake that answers "here are zero bytes" makes a
+            // streaming route look like it worked on an object that does not exist.
+            return new Response(null, { status: 404 });
+        },
+        async signToken(_claims, _ttlSeconds) {
+            return 'fake-token';
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.0.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.",
@@ -54,6 +54,24 @@
 			"source": "./src/server/bench/index.ts",
 			"import": "./dist/server/bench/index.js"
 		},
+		"./binary-store": {
+			"types": "./dist/server/storage/binaryStore.d.ts",
+			"bun": "./src/server/storage/binaryStore.ts",
+			"source": "./src/server/storage/binaryStore.ts",
+			"import": "./dist/server/storage/binaryStore.js"
+		},
+		"./binary-store/testing": {
+			"types": "./dist/server/storage/binaryStoreFake.d.ts",
+			"bun": "./src/server/storage/binaryStoreFake.ts",
+			"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

@@ -114,6 +114,43 @@ const LEAVES = [
     /** The failed-login backoff. Every app with a login door; shipped as 2.5.1. */
     evaluates: 'createLoginThrottle',
   },
+  {
+    subpath: './binary-store',
+    /**
+     * 🔴 The binary-server CLIENT, and the leaf whose promise is the largest. It arrived
+     * in 4.1.0 from five app-side copies, and it is the module that decides whether a ROM
+     * byte, a photograph, a song and a scanned document are readable — so every app takes
+     * it, and none of them may pay `sharp`/`otplib`/`kysely` for the privilege. It sits
+     * in `src/server/storage/` beside the file-catalogue and transcode graph, which is
+     * exactly the barrel this must never be reached through: `./storage`'s index is heavy
+     * and this module's whole point is that it costs `node:crypto` and nothing else.
+     */
+    evaluates: 'createBinaryStore',
+  },
+  {
+    subpath: './binary-store/testing',
+    /**
+     * The fake travels WITH the interface — it exists so that adding a method to
+     * `BinaryStore` stops breaking twenty-two suites in apps nobody touched, and a fake
+     * in a different package from its interface cannot do that job. Split from
+     * `./binary-store` so a consumer's PRODUCTION graph can never reach it, the same way
+     * `./d1/testing` is split from `./d1`.
+     */
+    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,
+			}),
 		};
 	}