cursedbelt-server 4.2.0 → 4.4.0

package/dist/server/bench/budget.d.ts

@@ -26,6 +26,10 @@
  * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
  * function to re-run against real traffic — the re-derivation is a call, not a paragraph
  * somebody has to remember to do.
+ *
+ * 🔴 **It has already been run once** — see {@link MEASURED_FLEET_REQUESTS_PER_DAY}, which
+ * carries both the number and the reason the default was left stricter than it. Do not
+ * spend that measurement again; what is still missing is Worker traffic, not Mac traffic.
  */
 /** CPU-milliseconds included in the Workers Paid plan each month. */
 export declare const WORKERS_PAID_INCLUDED_CPU_MS = 30000000;
@@ -42,6 +46,34 @@ export declare const WORKERS_PAID_USD_PER_MILLION_REQUESTS = 0.3;
 export declare const OWNER_PROJECTED_REQUESTS_PER_DAY = 100000;
 /** 365.25 / 12 — the average calendar month, since billing is monthly. */
 export declare const DAYS_PER_MONTH = 30.4375;
+/**
+ * 🔴 The re-derivation has been DONE — 2026-09-16 — and the answer was not 9.9. This
+ * constant exists so the next reader does not spend the measurement again.
+ *
+ * Summed from the six apps still holding a populated `request_metrics` table in
+ * `$FORGE_STATE/apps/<app>/metrics.sqlite` (rows ÷ retained window, since five of the
+ * six sit at a ~100,4xx retention cap and only `patterns` is a true count):
+ *
+ * ```
+ * family 15,489/d · roms 10,580/d · music 7,034/d · vault 5,690/d
+ * collections 3,737/d · patterns 442/d                →  42,971/day
+ * ```
+ *
+ * That is **43 % of {@link OWNER_PROJECTED_REQUESTS_PER_DAY}**, so the real per-request
+ * allowance is ~22.9 CPU-ms rather than 9.9 — 2.3× looser than the shipped default.
+ *
+ * 🔴 **The default was deliberately NOT raised to it**, and the reason is the corpus:
+ * every one of those tables stops within hours of its app's graduation (`roms` ends
+ * `2026-09-15 12:00:03`), because `requestLogger` has no callers in this generation
+ * yet. It is the RETIRED generation's traffic, and no app is on a Worker at all — so
+ * nothing here has been measured against the quantity Cloudflare actually bills.
+ * Loosening every budget in the fleet on evidence that cannot support it is the one
+ * direction a wrong guess costs money in; being 2.3× conservative costs nothing.
+ *
+ * `budget.spec.ts` holds that ordering as an assertion rather than as this paragraph:
+ * the default may never drift ABOVE the measured allowance without a red build.
+ */
+export declare const MEASURED_FLEET_REQUESTS_PER_DAY = 42971;
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -77,7 +109,9 @@ export declare function monthlyOverageUsd(opts: {
  * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
  *
  * Generous for a JSON route, tight for anything that renders, parses or derives a key.
- * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ *
+ * 🔴 Deliberately kept BELOW the ~22.9 ms that {@link MEASURED_FLEET_REQUESTS_PER_DAY}
+ * derives; that constant says why, and `budget.spec.ts` reddens if the two ever swap.
  */
 export declare const DEFAULT_ROUTE_CPU_BUDGET_MS: number;
 /** A route that is measured against a number. */

package/dist/server/bench/budget.js

@@ -26,6 +26,10 @@
  * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
  * function to re-run against real traffic — the re-derivation is a call, not a paragraph
  * somebody has to remember to do.
+ *
+ * 🔴 **It has already been run once** — see {@link MEASURED_FLEET_REQUESTS_PER_DAY}, which
+ * carries both the number and the reason the default was left stricter than it. Do not
+ * spend that measurement again; what is still missing is Worker traffic, not Mac traffic.
  */
 /** CPU-milliseconds included in the Workers Paid plan each month. */
 export const WORKERS_PAID_INCLUDED_CPU_MS = 30_000_000;
@@ -42,6 +46,34 @@ export const WORKERS_PAID_USD_PER_MILLION_REQUESTS = 0.3;
 export const OWNER_PROJECTED_REQUESTS_PER_DAY = 100_000;
 /** 365.25 / 12 — the average calendar month, since billing is monthly. */
 export const DAYS_PER_MONTH = 30.4375;
+/**
+ * 🔴 The re-derivation has been DONE — 2026-09-16 — and the answer was not 9.9. This
+ * constant exists so the next reader does not spend the measurement again.
+ *
+ * Summed from the six apps still holding a populated `request_metrics` table in
+ * `$FORGE_STATE/apps/<app>/metrics.sqlite` (rows ÷ retained window, since five of the
+ * six sit at a ~100,4xx retention cap and only `patterns` is a true count):
+ *
+ * ```
+ * family 15,489/d · roms 10,580/d · music 7,034/d · vault 5,690/d
+ * collections 3,737/d · patterns 442/d                →  42,971/day
+ * ```
+ *
+ * That is **43 % of {@link OWNER_PROJECTED_REQUESTS_PER_DAY}**, so the real per-request
+ * allowance is ~22.9 CPU-ms rather than 9.9 — 2.3× looser than the shipped default.
+ *
+ * 🔴 **The default was deliberately NOT raised to it**, and the reason is the corpus:
+ * every one of those tables stops within hours of its app's graduation (`roms` ends
+ * `2026-09-15 12:00:03`), because `requestLogger` has no callers in this generation
+ * yet. It is the RETIRED generation's traffic, and no app is on a Worker at all — so
+ * nothing here has been measured against the quantity Cloudflare actually bills.
+ * Loosening every budget in the fleet on evidence that cannot support it is the one
+ * direction a wrong guess costs money in; being 2.3× conservative costs nothing.
+ *
+ * `budget.spec.ts` holds that ordering as an assertion rather than as this paragraph:
+ * the default may never drift ABOVE the measured allowance without a red build.
+ */
+export const MEASURED_FLEET_REQUESTS_PER_DAY = 42_971;
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -78,7 +110,9 @@ export function monthlyOverageUsd(opts) {
  * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
  *
  * Generous for a JSON route, tight for anything that renders, parses or derives a key.
- * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ *
+ * 🔴 Deliberately kept BELOW the ~22.9 ms that {@link MEASURED_FLEET_REQUESTS_PER_DAY}
+ * derives; that constant says why, and `budget.spec.ts` reddens if the two ever swap.
  */
 export const DEFAULT_ROUTE_CPU_BUDGET_MS = Math.round(deriveCpuBudgetMs() * 10) / 10;
 export function isExemption(b) {

package/dist/server/bench/index.d.ts

@@ -33,7 +33,7 @@
  * alternative is a number that gets quoted as a billing fact.
  */
 export { type AssertCpuBudgetsOpts, assertCpuBudgets, checkCpuBudgets, type CpuViolation, type CpuViolationKind, formatCpuBudgetReport, } from './assert';
-export { type CpuBudgetConfig, type CpuBudgetExemption, type CpuBudgetLimit, DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, monthlyOverageUsd, OWNER_PROJECTED_REQUESTS_PER_DAY, type ResolvedBudget, resolveBudget, type RouteBudget, validateCpuBudgetConfig, WORKERS_PAID_INCLUDED_CPU_MS, WORKERS_PAID_INCLUDED_REQUESTS, WORKERS_PAID_USD_PER_MILLION_CPU_MS, WORKERS_PAID_USD_PER_MILLION_REQUESTS, } from './budget';
+export { type CpuBudgetConfig, type CpuBudgetExemption, type CpuBudgetLimit, DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, MEASURED_FLEET_REQUESTS_PER_DAY, monthlyOverageUsd, OWNER_PROJECTED_REQUESTS_PER_DAY, type ResolvedBudget, resolveBudget, type RouteBudget, validateCpuBudgetConfig, WORKERS_PAID_INCLUDED_CPU_MS, WORKERS_PAID_INCLUDED_REQUESTS, WORKERS_PAID_USD_PER_MILLION_CPU_MS, WORKERS_PAID_USD_PER_MILLION_REQUESTS, } from './budget';
 export { type CpuBudgetOpts, cpuBudget } from './cpuBudget';
 export { type CpuClock, type CpuSpan, fixedCpuClock, processCpuClock, resolveCpuClock, unavailableCpuClock, workerCpuClock, } from './cpuClock';
 export { type CpuBudgetReport, type CpuRecorder, type CpuRecorderOpts, createCpuRecorder, percentile, type RouteCpuStats, } from './recorder';

package/dist/server/bench/index.js

@@ -33,7 +33,7 @@
  * alternative is a number that gets quoted as a billing fact.
  */
 export { assertCpuBudgets, checkCpuBudgets, formatCpuBudgetReport, } from './assert';
-export { DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, monthlyOverageUsd, OWNER_PROJECTED_REQUESTS_PER_DAY, resolveBudget, validateCpuBudgetConfig, WORKERS_PAID_INCLUDED_CPU_MS, WORKERS_PAID_INCLUDED_REQUESTS, WORKERS_PAID_USD_PER_MILLION_CPU_MS, WORKERS_PAID_USD_PER_MILLION_REQUESTS, } from './budget';
+export { DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, MEASURED_FLEET_REQUESTS_PER_DAY, monthlyOverageUsd, OWNER_PROJECTED_REQUESTS_PER_DAY, resolveBudget, validateCpuBudgetConfig, WORKERS_PAID_INCLUDED_CPU_MS, WORKERS_PAID_INCLUDED_REQUESTS, WORKERS_PAID_USD_PER_MILLION_CPU_MS, WORKERS_PAID_USD_PER_MILLION_REQUESTS, } from './budget';
 export { cpuBudget } from './cpuBudget';
 export { fixedCpuClock, processCpuClock, resolveCpuClock, unavailableCpuClock, workerCpuClock, } from './cpuClock';
 export { createCpuRecorder, percentile, } from './recorder';

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

@@ -15,7 +15,7 @@
  * ```
  */
 export { backupFor, type BackupPoint, checkpointWal, createLocalBackup, createTimeTravelBackup, type DatabaseBackup, type LocalBackupOpts, type TimeTravelOpts, } from './backup';
-export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export { createRemoteD1, type D1BindingLike, type D1BindingMeta, type D1BindingResult, type D1BindingStatement, } from './remote';

package/dist/server/d1/index.js

@@ -15,7 +15,14 @@
  * ```
  */
 export { backupFor, checkpointWal, createLocalBackup, createTimeTravelBackup, } from './backup';
-export { createD1Kysely, D1LikeDialect } from './kysely';
+// 🔴 `./kysely` is deliberately NOT re-exported here — import it from
+// `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
+// `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it
+// made `import 'cursedbelt-server/d1'` throw `Cannot find package 'kysely'` for every app
+// that does not use the query builder — which per `../db/kysely.ts`'s own header is most
+// of them, since business tables stay on raw statements. Measured 2026-09-18 against the
+// published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
+export { perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export { createRemoteD1, } from './remote';

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

@@ -0,0 +1,72 @@
+/**
+ * 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 { type D1LikeDatabase } 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;
+}
+/**
+ * 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 declare function perInvocation(db: D1LikeDatabase, opts?: {
+    max?: number;
+}): InvocationD1;

package/dist/server/d1/invocation.js

@@ -0,0 +1,166 @@
+/**
+ * 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 } from './types';
+/**
+ * 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();
+class Budget {
+    max;
+    used = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    /** Charge before the work goes out, so the query over the cap is never issued. */
+    charge(n, what) {
+        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) {
+        this.used += n;
+    }
+}
+/** Wrap one statement so every terminal call is charged to `budget`. */
+function countedStatement(inner, budget, sql) {
+    const label = `\`${sql.trim().slice(0, 60)}\``;
+    class CountedStatement {
+        bind(...values) {
+            // 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(column) {
+            budget.charge(1, label);
+            return column === undefined ? inner.first() : inner.first(column);
+        }
+        async all() {
+            budget.charge(1, label);
+            return inner.all();
+        }
+        async run() {
+            budget.charge(1, label);
+            return inner.run();
+        }
+        async raw() {
+            budget.charge(1, label);
+            return inner.raw();
+        }
+    }
+    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, opts = {}) {
+    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) {
+            return countedStatement(db.prepare(sql), budget, sql);
+        },
+        async batch(statements) {
+            // One round trip, but D1 bills each member — so does this.
+            budget.charge(statements.length, `a batch() of ${statements.length}`);
+            return db.batch(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) {
+            budget.charge(1, 'an exec()');
+            const res = await db.exec(sql);
+            if (res.count > 1)
+                budget.settle(res.count - 1);
+            return res;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.2.0",
+	"version": "4.4.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.",
@@ -78,6 +78,12 @@
 			"source": "./src/server/d1/index.ts",
 			"import": "./dist/server/d1/index.js"
 		},
+		"./d1/kysely": {
+			"types": "./dist/server/d1/kysely.d.ts",
+			"bun": "./src/server/d1/kysely.ts",
+			"source": "./src/server/d1/kysely.ts",
+			"import": "./dist/server/d1/kysely.js"
+		},
 		"./d1/testing": {
 			"types": "./dist/server/d1/fakeD1.d.ts",
 			"bun": "./src/server/d1/fakeD1.ts",
@@ -258,7 +264,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/barrelsReachNoOptionalPeer.spec.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * A public subpath must not STATICALLY drag an OPTIONAL peer, because a static import is
+ * paid at import time by every consumer — including the ones that will never call it.
+ *
+ * ## 🔴 This is the same defect for the THIRD time, and the first two are why the rule is
+ * a check rather than a sentence
+ *
+ * `cursedbelt/src/barrelsReachNoOptionalPeer.spec.ts` carries the full history; the short
+ * version is that `apps/collections` once imported a TYPE from `cursedbelt/server/storage`
+ * and paid for it with `error: Cannot find package 'otplib'` and four dead route suites,
+ * because the barrel reached `streamToken.ts` → the `../auth` index → `totp.ts` → an
+ * optional peer. The app installed a one-time-password library to satisfy a claim shape.
+ *
+ * When the server tier split into this package (task 148), the RUNTIME-FIXTURE half came
+ * with it as `leafSubpathsImportNothing.spec.ts` — but that spec proves what a declared
+ * ZERO-RUNTIME LEAF pulls in, and a barrel is neither. So the barrel half stayed behind in
+ * `cursedbelt`, pointed at `./react`, and **this package shipped with no barrel check at
+ * all.**
+ *
+ * 🔴 It cost exactly what the first two cost, measured 2026-09-18 against the PUBLISHED
+ * `cursedbelt-server@4.3.0` tarball in a clean directory:
+ *
+ *     $ bun add cursedbelt-server && bun -e 'import "cursedbelt-server/d1"'
+ *     error: Cannot find package 'kysely' from …/src/server/d1/kysely.ts
+ *
+ * `./d1`'s index re-exported `./kysely`, which statically imports real VALUES from
+ * `kysely` (`Kysely`, `SqliteAdapter`, `SqliteQueryCompiler` — not types, so they cannot be
+ * erased). `kysely` is an optional peer. So the D1 seam — the thing the whole fleet is
+ * meant to port ONTO — could not be imported by any app that had not already installed a
+ * query builder, which by `../db/kysely.ts`'s own header is most of them: *"Business /
+ * `data JSON` tables stay on raw `db.query()` — do NOT add them here"*. The seam was
+ * unusable by precisely the apps it was built for.
+ *
+ * The fix was to give `createD1Kysely` its own subpath (`./d1/kysely`) and take it out of
+ * the barrel. This spec is what stops the fourth occurrence.
+ *
+ * ## What it measures
+ *
+ * Every subpath in the `exports` map is bundled with bare imports left external, and the
+ * remaining static specifiers are read out of the emitted JS. A DYNAMIC `await
+ * import('sharp')` inside the function that needs it matches neither branch of
+ * {@link STATIC_SPECIFIER} and must not — that is the lazy shape this file exists to
+ * permit, not forbid.
+ *
+ * ## Verified failing before it was trusted (2026-09-18)
+ *
+ *   · re-adding `export … from './kysely'` to `src/server/d1/index.ts`
+ *       → red: "./d1 statically drags optional peer(s): kysely"
+ *   · adding `import 'plainjob';` to `src/server/d1/local.ts` — two hops out of the
+ *     barrel, which grepping the index file cannot see
+ *       → red identically. That is the branch that matters.
+ *   · removing `'./jobs'` from {@link MAY_DRAG} → red, proving the allowlist is load-bearing
+ *     rather than decorative.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+/**
+ * The subpaths whose whole PURPOSE is the optional peer they pull, mapped to what they are
+ * allowed to pull and why. An entry here is a promise that the peer is the point of the
+ * subpath — not a place to park a new drag.
+ *
+ * 🔴 Measured 2026-09-18: these three are the ONLY subpaths in the map that reach an
+ * optional peer. Everything else is clean, which is what makes this list an allowlist
+ * rather than a baseline — it can only shrink.
+ */
+const MAY_DRAG: Record<string, readonly string[]> = {
+	// The whole-package barrel. It exists to re-export everything, so it necessarily reaches
+	// what the specific subpaths reach. An app importing `cursedbelt-server` whole is asking
+	// for that; an app importing `cursedbelt-server/d1` is not, and that is the distinction
+	// this spec protects.
+	'.': ['kysely', 'kysely-bun-sqlite', 'otplib', 'plainjob'],
+	// `createD1Kysely` IS the kysely adapter. Split out of `./d1` on 2026-09-18 precisely so
+	// the seam itself stops paying for it — see the header.
+	'./d1/kysely': ['kysely'],
+	// The job queue is plainjob. Nothing else here is.
+	'./jobs': ['plainjob'],
+};
+
+const OPTIONAL_PEERS = new Set(
+	Object.entries(
+		(pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ?? {},
+	)
+		.filter(([, meta]) => meta?.optional === true)
+		.map(([name]) => name),
+);
+
+/**
+ * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.
+ *
+ * Anchored on the `from` clause rather than on a line starting with `import`, so a
+ * multi-line named import still counts — bun emits `import {\n … \n} from "pkg";` and a
+ * line-anchored pattern silently misses it. A dynamic `import("pkg")` matches neither
+ * branch, which is deliberate.
+ */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+/** `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`. */
+const packageOf = (specifier: string): string | undefined => {
+	const parts = specifier.split('/');
+	return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+};
+
+/**
+ * Bundle one entry and return the bare packages it still imports.
+ *
+ * 🔴 A bundle that did not happen must never read as a subpath that pulls nothing, so a
+ * non-zero exit or an empty bundle THROWS rather than returning an empty set. That is the
+ * one way a check like this dies quietly.
+ */
+const staticExternalsOf = (entry: string, subpath: string): Set<string> => {
+	const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-server-barrel-scan/${subpath.replace(/[^a-z0-9]+/gi, '-')}`;
+	const build = Bun.spawnSync(['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir], {
+		cwd: REPO,
+		stdout: 'pipe',
+		stderr: 'pipe',
+	});
+	const emitted = [...new Bun.Glob('**/*.js').scanSync({ cwd: outdir, onlyFiles: true })];
+	const bundle = emitted.map((f) => readFileSync(`${outdir}/${f}`, 'utf8')).join('\n');
+	if (build.exitCode !== 0 || bundle.trim() === '') {
+		throw new Error(
+			`could not bundle ${subpath} (${entry}, exit ${build.exitCode}) — a check that cannot measure is not a passing check:\n${build.stderr.toString()}`,
+		);
+	}
+	const found = new Set<string>();
+	for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
+		const specifier = match[1] ?? match[2];
+		if (specifier === undefined || specifier.startsWith('.') || specifier.startsWith('bun:')) continue;
+		const name = packageOf(specifier);
+		if (name !== undefined) found.add(name);
+	}
+	return found;
+};
+
+/** Every subpath with a `source` entry — the ones whose real graph can be measured. */
+const SUBPATHS = Object.entries(pkg.exports as Record<string, { source?: string }>)
+	.filter(([, e]) => typeof e?.source === 'string' && /\.tsx?$/.test(e.source))
+	.map(([subpath, e]) => ({ subpath, entry: (e as { source: string }).source }));
+
+describe('no public subpath statically drags an optional peer', () => {
+	it('measures a non-trivial number of subpaths, so a broken exports map cannot pass vacuously', () => {
+		expect(SUBPATHS.length).toBeGreaterThan(20);
+		expect(OPTIONAL_PEERS.size).toBeGreaterThan(0);
+	});
+
+	for (const { subpath, entry } of SUBPATHS) {
+		const allowed = MAY_DRAG[subpath] ?? [];
+		it(`${subpath} drags ${allowed.length === 0 ? 'no optional peer' : allowed.join(' + ') + ' and nothing more'}`, () => {
+			const dragged = [...staticExternalsOf(entry, subpath)].filter((n) => OPTIONAL_PEERS.has(n)).sort();
+			const unexpected = dragged.filter((n) => !allowed.includes(n));
+			expect(
+				unexpected,
+				`${subpath} statically drags optional peer(s): ${unexpected.join(', ')}\n` +
+					`  Every app importing '${pkg.name}${subpath.slice(1)}' must now install them or crash on import.\n` +
+					`  Give the adapter its own subpath and take it out of this barrel — see ./d1/kysely, which is\n` +
+					`  exactly this fix applied on 2026-09-18 after the published 4.3.0 could not be imported at all.`,
+			).toEqual([]);
+
+			// The allowlist may only shrink: an entry that no longer drags what it promised is
+			// a stale exception, and a stale exception is how a list like this stops meaning
+			// anything.
+			const stale = allowed.filter((n) => !dragged.includes(n));
+			expect(stale, `${subpath} is allowed to drag ${stale.join(', ')} but no longer does — remove the exception`).toEqual(
+				[],
+			);
+		});
+	}
+});

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', () => {

package/src/server/bench/budget.ts

@@ -26,6 +26,10 @@
  * which is the owner's estimate and not a measurement. {@link deriveCpuBudgetMs} is the
  * function to re-run against real traffic — the re-derivation is a call, not a paragraph
  * somebody has to remember to do.
+ *
+ * 🔴 **It has already been run once** — see {@link MEASURED_FLEET_REQUESTS_PER_DAY}, which
+ * carries both the number and the reason the default was left stricter than it. Do not
+ * spend that measurement again; what is still missing is Worker traffic, not Mac traffic.
  */
 
 /** CPU-milliseconds included in the Workers Paid plan each month. */
@@ -49,6 +53,35 @@ export const OWNER_PROJECTED_REQUESTS_PER_DAY = 100_000;
 /** 365.25 / 12 — the average calendar month, since billing is monthly. */
 export const DAYS_PER_MONTH = 30.4375;
 
+/**
+ * 🔴 The re-derivation has been DONE — 2026-09-16 — and the answer was not 9.9. This
+ * constant exists so the next reader does not spend the measurement again.
+ *
+ * Summed from the six apps still holding a populated `request_metrics` table in
+ * `$FORGE_STATE/apps/<app>/metrics.sqlite` (rows ÷ retained window, since five of the
+ * six sit at a ~100,4xx retention cap and only `patterns` is a true count):
+ *
+ * ```
+ * family 15,489/d · roms 10,580/d · music 7,034/d · vault 5,690/d
+ * collections 3,737/d · patterns 442/d                →  42,971/day
+ * ```
+ *
+ * That is **43 % of {@link OWNER_PROJECTED_REQUESTS_PER_DAY}**, so the real per-request
+ * allowance is ~22.9 CPU-ms rather than 9.9 — 2.3× looser than the shipped default.
+ *
+ * 🔴 **The default was deliberately NOT raised to it**, and the reason is the corpus:
+ * every one of those tables stops within hours of its app's graduation (`roms` ends
+ * `2026-09-15 12:00:03`), because `requestLogger` has no callers in this generation
+ * yet. It is the RETIRED generation's traffic, and no app is on a Worker at all — so
+ * nothing here has been measured against the quantity Cloudflare actually bills.
+ * Loosening every budget in the fleet on evidence that cannot support it is the one
+ * direction a wrong guess costs money in; being 2.3× conservative costs nothing.
+ *
+ * `budget.spec.ts` holds that ordering as an assertion rather than as this paragraph:
+ * the default may never drift ABOVE the measured allowance without a red build.
+ */
+export const MEASURED_FLEET_REQUESTS_PER_DAY = 42_971;
+
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -100,7 +133,9 @@ export function monthlyOverageUsd(opts: {
  * 9.9 CPU-ms — `30,000,000 ÷ (100,000 × 30.4375)` = 9.856, to one decimal.
  *
  * Generous for a JSON route, tight for anything that renders, parses or derives a key.
- * 🔴 Re-derive with {@link deriveCpuBudgetMs} once an app has real traffic.
+ *
+ * 🔴 Deliberately kept BELOW the ~22.9 ms that {@link MEASURED_FLEET_REQUESTS_PER_DAY}
+ * derives; that constant says why, and `budget.spec.ts` reddens if the two ever swap.
  */
 export const DEFAULT_ROUTE_CPU_BUDGET_MS = Math.round(deriveCpuBudgetMs() * 10) / 10;
 

package/src/server/bench/index.ts

@@ -49,6 +49,7 @@ export {
   DEFAULT_ROUTE_CPU_BUDGET_MS,
   deriveCpuBudgetMs,
   isExemption,
+  MEASURED_FLEET_REQUESTS_PER_DAY,
   monthlyOverageUsd,
   OWNER_PROJECTED_REQUESTS_PER_DAY,
   type ResolvedBudget,

package/src/server/d1/index.ts

@@ -25,7 +25,14 @@ export {
 	type LocalBackupOpts,
 	type TimeTravelOpts,
 } from './backup';
-export { createD1Kysely, D1LikeDialect, type D1PlumbingDb } from './kysely';
+// 🔴 `./kysely` is deliberately NOT re-exported here — import it from
+// `cursedbelt-server/d1/kysely`. It statically imports `kysely` (real values: `Kysely`,
+// `SqliteAdapter`, `SqliteQueryCompiler`), which is an OPTIONAL peer, so re-exporting it
+// made `import 'cursedbelt-server/d1'` throw `Cannot find package 'kysely'` for every app
+// that does not use the query builder — which per `../db/kysely.ts`'s own header is most
+// of them, since business tables stay on raw statements. Measured 2026-09-18 against the
+// published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
+export { type InvocationD1, perInvocation } from './invocation';
 export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits';
 export { createLocalD1, refuseInteractiveTransaction } from './local';
 export {

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

@@ -0,0 +1,174 @@
+import { Database } from 'bun:sqlite';
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { createFakeD1Binding } from './fakeD1';
+import { perInvocation } from './invocation';
+import { LIMITS } from './limits';
+import { createLocalD1 } from './local';
+import { createRemoteD1 } from './remote';
+import { D1LimitError, type D1LikeDatabase } from './types';
+
+/**
+ * 🔴 Every test here would have passed against the seam as published in 4.2.0, because
+ * nothing counted. `assertBatchSize` guards the length of one `batch()`; the N+1 loop
+ * below never builds a batch at all.
+ */
+
+const seeded = () => {
+	const db = new Database(':memory:');
+	db.run('CREATE TABLE people (id INTEGER PRIMARY KEY, name TEXT)');
+	for (let i = 1; i <= 5; i++) db.run('INSERT INTO people (id, name) VALUES (?, ?)', [i, `p${i}`]);
+	return db;
+};
+
+describe('the per-invocation query budget', () => {
+	let base: D1LikeDatabase;
+
+	beforeEach(() => {
+		base = createLocalD1(seeded());
+	});
+
+	test('🔴 the N+1 loop the limits header names is refused — and it is the case nothing caught before', async () => {
+		const db = perInvocation(base, { max: 10 });
+		// The laziest mechanical port of a synchronous loop: await inside `for`.
+		const run = async () => {
+			for (let i = 0; i < 50; i++) {
+				await db.prepare('SELECT name FROM people WHERE id = ?').bind(1).first();
+			}
+		};
+		await expect(run()).rejects.toThrow(D1LimitError);
+		// It stopped AT the cap, not after it — the query over budget was never issued.
+		expect(db.used).toBe(10);
+		expect(db.remaining).toBe(0);
+	});
+
+	test('the refusal names the remedy rather than the number', async () => {
+		const db = perInvocation(base, { max: 1 });
+		await db.prepare('SELECT 1 AS n').all();
+		try {
+			await db.prepare('SELECT 2 AS n').all();
+			throw new Error('expected a refusal');
+		} catch (e) {
+			expect(e).toBeInstanceOf(D1LimitError);
+			const msg = (e as Error).message;
+			expect(msg).toContain('N+1');
+			expect(msg).toContain('JOIN');
+			expect(msg).toContain('batch()');
+		}
+	});
+
+	test('the JOIN that replaces the loop costs one query', async () => {
+		const db = perInvocation(base, { max: 1 });
+		const res = await db.prepare('SELECT id, name FROM people ORDER BY id').all();
+		expect(res.results).toHaveLength(5);
+		expect(db.used).toBe(1);
+	});
+
+	test('every terminal call is charged, and building a statement is not', async () => {
+		const db = perInvocation(base);
+		// prepare + bind reach nothing, so they cost nothing — otherwise a re-bound
+		// statement kept in a helper would bill for merely existing.
+		const stmt = db.prepare('SELECT name FROM people WHERE id = ?').bind(1);
+		expect(db.used).toBe(0);
+
+		await stmt.first();
+		await stmt.all();
+		await stmt.raw();
+		await db.prepare('INSERT INTO people (id, name) VALUES (?, ?)').bind(99, 'x').run();
+		expect(db.used).toBe(4);
+	});
+
+	test('a batch is charged per MEMBER, because D1 bills it that way', async () => {
+		const db = perInvocation(base);
+		const stmts = [1, 2, 3].map((i) => db.prepare('SELECT name FROM people WHERE id = ?').bind(i));
+		const out = await db.batch(stmts);
+		expect(out).toHaveLength(3);
+		expect(db.used).toBe(3);
+	});
+
+	test('🔴 batch() still works through the wrapper — the statements are unwrapped for the driver', async () => {
+		// The regression this guards: both drivers identify their own statements
+		// structurally (`allSync` local, `binding` remote) and reject anything else. A
+		// wrapper that forwarded itself would break batch() on both sides.
+		const db = perInvocation(base);
+		const stmts = [
+			db.prepare('INSERT INTO people (id, name) VALUES (?, ?)').bind(20, 'a'),
+			db.prepare('INSERT INTO people (id, name) VALUES (?, ?)').bind(21, 'b'),
+		];
+		await db.batch(stmts);
+		const check = await db.prepare('SELECT COUNT(*) AS n FROM people').first<{ n: number }>();
+		expect(check?.n).toBe(7);
+	});
+
+	test('a batch that would exceed the remaining budget is refused before it is sent', async () => {
+		const db = perInvocation(base, { max: 2 });
+		const stmts = [1, 2, 3].map((i) => db.prepare('SELECT name FROM people WHERE id = ?').bind(i));
+		await expect(db.batch(stmts)).rejects.toThrow(D1LimitError);
+		// Nothing was charged, because nothing was sent.
+		expect(db.used).toBe(0);
+	});
+
+	test('exec settles its true cost afterwards, and the NEXT query is what refuses', async () => {
+		const db = perInvocation(base, { max: 3 });
+		// Three statements through a budget of three: exec reserves one, then settles two.
+		const res = await db.exec('CREATE TABLE a (x); CREATE TABLE b (x); CREATE TABLE c (x)');
+		expect(res.count).toBe(3);
+		expect(db.used).toBe(3);
+		await expect(db.prepare('SELECT 1 AS n').all()).rejects.toThrow(D1LimitError);
+	});
+
+	test('the cap is not off by one — exactly `max` queries are allowed', async () => {
+		const db = perInvocation(base, { max: 3 });
+		for (let i = 0; i < 3; i++) await db.prepare('SELECT 1 AS n').all();
+		expect(db.used).toBe(3);
+		await expect(db.prepare('SELECT 1 AS n').all()).rejects.toThrow(D1LimitError);
+	});
+
+	test('the default budget is D1\'s own, and `remaining` starts there', () => {
+		const db = perInvocation(base);
+		expect(db.remaining).toBe(LIMITS.queriesPerInvocation);
+		expect(db.used).toBe(0);
+	});
+
+	test('a budget above D1\'s real cap is refused rather than honoured', () => {
+		expect(() => perInvocation(base, { max: LIMITS.queriesPerInvocation + 1 })).toThrow(D1LimitError);
+		expect(() => perInvocation(base, { max: 0 })).toThrow(RangeError);
+		expect(() => perInvocation(base, { max: 1.5 })).toThrow(RangeError);
+	});
+
+	test('the flavor of the wrapped driver shows through', () => {
+		expect(perInvocation(base).flavor).toBe('local');
+	});
+
+	test('🔴 each invocation gets its own budget — the count is the request\'s, not the handle\'s', async () => {
+		// The false positive this design avoids: `createLocalD1` lives for the whole
+		// process, so a counter on the HANDLE would refuse the 1,001st query of the day.
+		for (let request = 0; request < 3; request++) {
+			const db = perInvocation(base, { max: 2 });
+			await db.prepare('SELECT 1 AS n').all();
+			await db.prepare('SELECT 1 AS n').all();
+			expect(db.used).toBe(2);
+		}
+	});
+});
+
+describe('the budget counts the REMOTE driver identically', () => {
+	// Same assertions, other side of the seam — a budget that only worked locally would be
+	// the sync-locally defect over again.
+	test('the loop is refused on D1 too, at the same point', async () => {
+		const db = perInvocation(createRemoteD1(createFakeD1Binding(seeded())), { max: 4 });
+		expect(db.flavor).toBe('d1');
+		const run = async () => {
+			for (let i = 0; i < 20; i++) await db.prepare('SELECT name FROM people WHERE id = ?').bind(1).first();
+		};
+		await expect(run()).rejects.toThrow(D1LimitError);
+		expect(db.used).toBe(4);
+	});
+
+	test('batch() unwraps for the remote driver as well', async () => {
+		const db = perInvocation(createRemoteD1(createFakeD1Binding(seeded())));
+		const stmts = [1, 2].map((i) => db.prepare('SELECT name FROM people WHERE id = ?').bind(i));
+		const out = await db.batch(stmts);
+		expect(out).toHaveLength(2);
+		expect(db.used).toBe(2);
+	});
+});

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