cursedbelt-server 4.1.0 → 4.3.0

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

@@ -16,7 +16,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;
     /** `'GET /api/notes/:id'`. */
@@ -43,10 +47,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;
 }
 /** Compute violations without throwing. {@link assertCpuBudgets} is this plus a throw. */
 export declare function checkCpuBudgets(report: CpuBudgetReport, opts?: AssertCpuBudgetsOpts): CpuViolation[];

package/dist/server/bench/assert.js

@@ -27,6 +27,60 @@ export function checkCpuBudgets(report, opts = {}) {
             },
         ];
     }
+    // 🔴 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 = {
             key: r.key,

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/cpuClock.js

@@ -51,13 +51,33 @@ export function processCpuClock() {
  * @param readCpuMs Returns monotonically non-decreasing CPU-ms for the current invocation.
  */
 export function workerCpuClock(readCpuMs, source = 'worker-runtime') {
+    // 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() {
             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/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/fakeD1.d.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.

package/dist/server/d1/fakeD1.js

@@ -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.
@@ -28,6 +33,7 @@
  * makes a port testable on a laptop, and `190`'s Worker preview is the thing that proves
  * it.
  */
+import { isPureReadSql } from './values';
 /** The bind types a real D1 binding accepts. Everything else throws. */
 function assertD1Bindable(value, index) {
     if (value === null)
@@ -128,7 +134,48 @@ class FakeD1Statement {
         const rows = this.db.query(this.sql).values(...this.params);
         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() {
+        assertRunnableOnD1(this.sql);
+        const started = performance.now();
+        const stmt = this.db.query(this.sql);
+        const bound = this.params;
+        // 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);
+            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);
+        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) => db.query('SELECT total_changes() AS n').get().n;
+/** The connection's last inserted rowid, which is what D1 puts in `meta.last_row_id`. */
+const lastInsertRowid = (db) => db.query('SELECT last_insert_rowid() AS r').get().r;
 /**
  * Wrap a real `bun:sqlite` database in D1's API and D1's restrictions.
  *
@@ -145,26 +192,12 @@ export function createFakeD1Binding(db) {
         async batch(statements) {
             // 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 = [];
             const run = db.transaction((stmts) => {
-                for (const s of stmts) {
-                    const started = performance.now();
-                    const inner = s;
-                    assertRunnableOnD1(inner.sql);
-                    const rows = db.query(inner.sql).all(...inner.params);
-                    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.runSync());
             });
             run(statements);
             return results;

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

@@ -16,6 +16,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

@@ -16,6 +16,7 @@
  */
 export { backupFor, checkpointWal, createLocalBackup, createTimeTravelBackup, } from './backup';
 export { createD1Kysely, D1LikeDialect } from './kysely';
+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;
+        },
+    };
+}