cursedbelt-server 4.22.0 → 4.23.0

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

@@ -74,6 +74,47 @@ export declare const DAYS_PER_MONTH = 30.4375;
  * the default may never drift ABOVE the measured allowance without a red build.
  */
 export declare const MEASURED_FLEET_REQUESTS_PER_DAY = 42971;
+/**
+ * 🔴 The WORKER re-derivation — 2026-09-23 (task 083, bullet 3). Cloudflare's own numbers,
+ * not a proxy: the account's `workersInvocationsAdaptive` dataset (GraphQL Analytics API,
+ * `sum { requests cpuTimeUs }` by `scriptName`) over the seven whole days
+ * 2026-09-16T00:00Z → 2026-09-23T00:00Z, while `patterns` (since 09-18) and `collections`
+ * (since 09-22) served from Workers:
+ *
+ * ```
+ * script                    requests    billed CPU-ms   mean
+ * binary-server-edge-gate    754,974       1,805,750    2.39
+ * collections                    350         171,228  489.2   (09-22: p99 15.2 s — one-off imports)
+ * collections-stage               61          96,081   1575    (stage: seeding and gate runs)
+ * patterns                       424          12,718   30.0    (09-18: p99 2.9 s, first boot)
+ * 3 others                       196             126
+ * ACCOUNT                    756,005       2,085,903    2.76  →  108,001 req/day, 9.07 M CPU-ms/month (30 %)
+ * ```
+ *
+ * **What the call says.** `deriveCpuBudgetMs({ requestsPerDay: 108_001 })` = **9.1**, i.e.
+ * BELOW the shipped 9.9 — the account already carries more requests than the owner's
+ * 100,000/day projection. **The default did not move, and this is why:** 99.9 % of those
+ * requests are the binary server's edge gate, a fixed-cost auth check at 2.39 CPU-ms mean
+ * that no app route budget governs. Averaging them in hands the app routes an allowance
+ * those requests never use. The question the default answers is what an APP request may
+ * spend once the measured non-app spend is set aside:
+ * `deriveCpuBudgetMs({ requestsPerDay: MEASURED_FLEET_REQUESTS_PER_DAY, reservedCpuMsPerMonth: edge gate })`
+ * = **16.9** CPU-ms — the fleet's whole app traffic (42,971/day, above) on Workers, with the
+ * edge gate still running beside it. 9.9 stays under that with 1.7× headroom, and the
+ * account is at 30 % of its CPU allowance, so there is no evidence for tightening it either.
+ * App-Worker traffic itself (~111/day, mostly agent deploy checks) is too small to derive
+ * anything from yet. `budget.spec.ts` holds both orderings as assertions.
+ */
+export declare const MEASURED_WORKER_TRAFFIC: {
+    readonly from: "2026-09-16T00:00:00Z";
+    readonly until: "2026-09-23T00:00:00Z";
+    readonly days: 7;
+    readonly requests: 756005;
+    readonly cpuMs: 2085903;
+    /** The binary server's edge gate — fixed-cost traffic no app route budget governs. */
+    readonly edgeGateRequests: 754974;
+    readonly edgeGateCpuMs: 1805750;
+};
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -90,6 +131,12 @@ export declare function deriveCpuBudgetMs(opts?: {
     requestsPerMonth?: number;
     /** Measured (or projected) requests per day — converted with {@link DAYS_PER_MONTH}. */
     requestsPerDay?: number;
+    /**
+     * CPU-ms per month already spent by traffic OUTSIDE the budgeted routes (measured —
+     * the edge gate in {@link MEASURED_WORKER_TRAFFIC}), taken off the allowance first.
+     * Default: 0.
+     */
+    reservedCpuMsPerMonth?: number;
 }): number;
 /**
  * What a month costs in overage once the included allowances are spent. Used by the
@@ -112,6 +159,9 @@ export declare function monthlyOverageUsd(opts: {
  *
  * 🔴 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.
+ *
+ * Re-derived from WORKER traffic on 2026-09-23 and kept: {@link MEASURED_WORKER_TRAFFIC}
+ * has the numbers (16.9 ms per app request after the edge gate's measured spend).
  */
 export declare const DEFAULT_ROUTE_CPU_BUDGET_MS: number;
 /** A route that is measured against a number. */

package/dist/server/bench/budget.js

@@ -74,6 +74,47 @@ export const DAYS_PER_MONTH = 30.4375;
  * the default may never drift ABOVE the measured allowance without a red build.
  */
 export const MEASURED_FLEET_REQUESTS_PER_DAY = 42_971;
+/**
+ * 🔴 The WORKER re-derivation — 2026-09-23 (task 083, bullet 3). Cloudflare's own numbers,
+ * not a proxy: the account's `workersInvocationsAdaptive` dataset (GraphQL Analytics API,
+ * `sum { requests cpuTimeUs }` by `scriptName`) over the seven whole days
+ * 2026-09-16T00:00Z → 2026-09-23T00:00Z, while `patterns` (since 09-18) and `collections`
+ * (since 09-22) served from Workers:
+ *
+ * ```
+ * script                    requests    billed CPU-ms   mean
+ * binary-server-edge-gate    754,974       1,805,750    2.39
+ * collections                    350         171,228  489.2   (09-22: p99 15.2 s — one-off imports)
+ * collections-stage               61          96,081   1575    (stage: seeding and gate runs)
+ * patterns                       424          12,718   30.0    (09-18: p99 2.9 s, first boot)
+ * 3 others                       196             126
+ * ACCOUNT                    756,005       2,085,903    2.76  →  108,001 req/day, 9.07 M CPU-ms/month (30 %)
+ * ```
+ *
+ * **What the call says.** `deriveCpuBudgetMs({ requestsPerDay: 108_001 })` = **9.1**, i.e.
+ * BELOW the shipped 9.9 — the account already carries more requests than the owner's
+ * 100,000/day projection. **The default did not move, and this is why:** 99.9 % of those
+ * requests are the binary server's edge gate, a fixed-cost auth check at 2.39 CPU-ms mean
+ * that no app route budget governs. Averaging them in hands the app routes an allowance
+ * those requests never use. The question the default answers is what an APP request may
+ * spend once the measured non-app spend is set aside:
+ * `deriveCpuBudgetMs({ requestsPerDay: MEASURED_FLEET_REQUESTS_PER_DAY, reservedCpuMsPerMonth: edge gate })`
+ * = **16.9** CPU-ms — the fleet's whole app traffic (42,971/day, above) on Workers, with the
+ * edge gate still running beside it. 9.9 stays under that with 1.7× headroom, and the
+ * account is at 30 % of its CPU allowance, so there is no evidence for tightening it either.
+ * App-Worker traffic itself (~111/day, mostly agent deploy checks) is too small to derive
+ * anything from yet. `budget.spec.ts` holds both orderings as assertions.
+ */
+export const MEASURED_WORKER_TRAFFIC = {
+    from: '2026-09-16T00:00:00Z',
+    until: '2026-09-23T00:00:00Z',
+    days: 7,
+    requests: 756_005,
+    cpuMs: 2_085_903,
+    /** The binary server's edge gate — fixed-cost traffic no app route budget governs. */
+    edgeGateRequests: 754_974,
+    edgeGateCpuMs: 1_805_750,
+};
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -84,7 +125,11 @@ export const MEASURED_FLEET_REQUESTS_PER_DAY = 42_971;
  * allowed to become the common case.
  */
 export function deriveCpuBudgetMs(opts = {}) {
-    const includedCpuMs = opts.includedCpuMs ?? WORKERS_PAID_INCLUDED_CPU_MS;
+    const reserved = opts.reservedCpuMsPerMonth ?? 0;
+    const includedCpuMs = (opts.includedCpuMs ?? WORKERS_PAID_INCLUDED_CPU_MS) - reserved;
+    if (!(reserved >= 0) || !(includedCpuMs > 0)) {
+        throw new Error(`deriveCpuBudgetMs: reservedCpuMsPerMonth (${reserved}) must be ≥ 0 and leave some allowance`);
+    }
     const requestsPerMonth = opts.requestsPerMonth ??
         (opts.requestsPerDay ?? OWNER_PROJECTED_REQUESTS_PER_DAY) * DAYS_PER_MONTH;
     if (!(requestsPerMonth > 0)) {
@@ -113,6 +158,9 @@ export function monthlyOverageUsd(opts) {
  *
  * 🔴 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.
+ *
+ * Re-derived from WORKER traffic on 2026-09-23 and kept: {@link MEASURED_WORKER_TRAFFIC}
+ * has the numbers (16.9 ms per app request after the edge gate's measured spend).
  */
 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.js';
-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.js';
+export { type CpuBudgetConfig, type CpuBudgetExemption, type CpuBudgetLimit, DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, MEASURED_FLEET_REQUESTS_PER_DAY, MEASURED_WORKER_TRAFFIC, 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.js';
 export { type CpuBudgetOpts, cpuBudget } from './cpuBudget.js';
 export { type CpuClock, type CpuSpan, fixedCpuClock, processCpuClock, resolveCpuClock, unavailableCpuClock, workerCpuClock, } from './cpuClock.js';
 export { type CpuBudgetReport, type CpuRecorder, type CpuRecorderOpts, createCpuRecorder, percentile, type RouteCpuStats, } from './recorder.js';

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.js';
-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.js';
+export { DAYS_PER_MONTH, DEFAULT_ROUTE_CPU_BUDGET_MS, deriveCpuBudgetMs, isExemption, MEASURED_FLEET_REQUESTS_PER_DAY, MEASURED_WORKER_TRAFFIC, 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.js';
 export { cpuBudget } from './cpuBudget.js';
 export { fixedCpuClock, processCpuClock, resolveCpuClock, unavailableCpuClock, workerCpuClock, } from './cpuClock.js';
 export { createCpuRecorder, percentile, } from './recorder.js';

package/dist/server/metrics/metricsBuffer.d.ts

@@ -18,7 +18,17 @@ export interface MetricRow {
     durationMs: number | null;
     bytesOut: number | null;
     userId: string | null;
+    /**
+     * Where the request came from — a PLACE, never an address (4.23.0). Filled by
+     * `requestLogger`'s `locate` hook; absent/null when nothing could place it. There is
+     * deliberately no `ip` field: the raw address is never stored, anywhere.
+     */
+    country?: string | null;
+    region?: string | null;
+    city?: string | null;
 }
+/** The optional place columns, in insert order. Each is written only when the table HAS it. */
+export declare const PLACE_COLUMNS: readonly ["country", "region", "city"];
 export interface MetricsBufferOptions {
     db: Database;
     /** Flush cadence in ms. Default: 1500. */

package/dist/server/metrics/metricsBuffer.js

@@ -1,11 +1,19 @@
+/** The optional place columns, in insert order. Each is written only when the table HAS it. */
+export const PLACE_COLUMNS = ['country', 'region', 'city'];
 export function createMetricsBuffer(opts) {
     const { db, flushIntervalMs = 1500, maxSize = 5000 } = opts;
     let buffer = [];
-    const insert = db.prepare(`INSERT INTO request_metrics (id, ts, method, route, status, duration_ms, bytes_out, user_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    // 🔴 The place columns are written only where the table has them (4.23.0). An app that
+    // created `request_metrics` with its own DDL before they existed keeps working unchanged —
+    // a fixed column list would make `prepare` throw on its first boot after the bump.
+    const present = new Set(db.query('PRAGMA table_info(request_metrics)').all().map((c) => c.name));
+    const place = PLACE_COLUMNS.filter((c) => present.has(c));
+    const columns = ['id', 'ts', 'method', 'route', 'status', 'duration_ms', 'bytes_out', 'user_id', ...place];
+    const insert = db.prepare(`INSERT INTO request_metrics (${columns.join(', ')})
+     VALUES (${columns.map(() => '?').join(', ')})`);
     const insertMany = db.transaction((rows) => {
         for (const r of rows) {
-            insert.run(crypto.randomUUID(), r.ts, r.method, r.route, r.status, r.durationMs, r.bytesOut, r.userId);
+            insert.run(crypto.randomUUID(), r.ts, r.method, r.route, r.status, r.durationMs, r.bytesOut, r.userId, ...place.map((c) => r[c] ?? null));
         }
     });
     const flush = () => {

package/dist/server/metrics/requestPlace.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where a request came from — as a PLACE, never as an address (4.23.0, task 2123).
+ *
+ * ── 🔴 The raw IP is never stored ───────────────────────────────────────────
+ * The retired instances' logger wrote `ip` on every row. This one does not, anywhere: not in
+ * `request_metrics`, not in an Analytics Engine blob. A {@link RequestLocator} receives the
+ * `Request`, may read whatever address it needs from it (`cf-connecting-ip` behind the tunnel),
+ * and returns only `{ country, region?, city? }`. The address dies with the request. That is
+ * the owner's privacy choice, fixed in the type rather than in a comment: {@link RequestPlace}
+ * has no field an address could go in, and {@link normalizePlace} copies only those three.
+ *
+ * ── The default reads the edge ──────────────────────────────────────────────
+ * {@link locateFromCloudflare} is what `requestLogger` uses when an app passes no `locate`:
+ *
+ *   - on a Worker, `request.cf.country/region/city` — Cloudflare's own geolocation;
+ *   - behind the tunnel (a Mac app), the `cf-ipcountry` header every proxied request carries,
+ *     plus `cf-region`/`cf-ipcity` when the zone's "visitor location headers" transform is on.
+ *
+ * A Bun process reached directly (dev, tests) has neither, and gets `null` — an unplaced row,
+ * never an invented one. An app that can do better (station's DB-IP snapshot) passes its own
+ * `locate`, and should merge per field with this one so the edge wins wherever it speaks.
+ *
+ * Worker-safe: no `bun:` import (`telemetryIsWorkerSafe.spec.ts` walks this graph).
+ */
+/** A place. `country` is an ISO-3166 alpha-2 code as the edge spells it (`US`, `IE`, `T1` for Tor). */
+export interface RequestPlace {
+    country: string;
+    region?: string | null;
+    city?: string | null;
+}
+/** Place one request, or `null` when it cannot. Must not throw — but a throw is caught and read as `null`. */
+export type RequestLocator = (request: Request) => RequestPlace | null;
+/** Each place field is capped so three of them can never crowd the 5120-byte Analytics Engine blob budget. */
+export declare const PLACE_FIELD_MAX_CHARS = 96;
+/**
+ * The three columns a row stores, from whatever a locator returned. Copies ONLY
+ * `country/region/city` — so a locator that returns extra fields (an `ip`, say) cannot get them
+ * written — and treats an empty or unknown country as no place at all.
+ */
+export declare function normalizePlace(place: RequestPlace | null | undefined): {
+    country: string | null;
+    region: string | null;
+    city: string | null;
+};
+/** The edge's own answer: `request.cf` on a Worker, the `cf-*` headers behind the tunnel, else `null`. */
+export declare const locateFromCloudflare: RequestLocator;
+/** Run a locator the way the logger must: a throw is an unplaced request, never a failed one. */
+export declare function placeOf(locate: RequestLocator, request: Request): ReturnType<typeof normalizePlace>;

package/dist/server/metrics/requestPlace.js

@@ -0,0 +1,77 @@
+/**
+ * Where a request came from — as a PLACE, never as an address (4.23.0, task 2123).
+ *
+ * ── 🔴 The raw IP is never stored ───────────────────────────────────────────
+ * The retired instances' logger wrote `ip` on every row. This one does not, anywhere: not in
+ * `request_metrics`, not in an Analytics Engine blob. A {@link RequestLocator} receives the
+ * `Request`, may read whatever address it needs from it (`cf-connecting-ip` behind the tunnel),
+ * and returns only `{ country, region?, city? }`. The address dies with the request. That is
+ * the owner's privacy choice, fixed in the type rather than in a comment: {@link RequestPlace}
+ * has no field an address could go in, and {@link normalizePlace} copies only those three.
+ *
+ * ── The default reads the edge ──────────────────────────────────────────────
+ * {@link locateFromCloudflare} is what `requestLogger` uses when an app passes no `locate`:
+ *
+ *   - on a Worker, `request.cf.country/region/city` — Cloudflare's own geolocation;
+ *   - behind the tunnel (a Mac app), the `cf-ipcountry` header every proxied request carries,
+ *     plus `cf-region`/`cf-ipcity` when the zone's "visitor location headers" transform is on.
+ *
+ * A Bun process reached directly (dev, tests) has neither, and gets `null` — an unplaced row,
+ * never an invented one. An app that can do better (station's DB-IP snapshot) passes its own
+ * `locate`, and should merge per field with this one so the edge wins wherever it speaks.
+ *
+ * Worker-safe: no `bun:` import (`telemetryIsWorkerSafe.spec.ts` walks this graph).
+ */
+/** Each place field is capped so three of them can never crowd the 5120-byte Analytics Engine blob budget. */
+export const PLACE_FIELD_MAX_CHARS = 96;
+/** Cloudflare's "no country could be determined" code — an unknown, not a place. */
+const UNKNOWN_COUNTRY = 'XX';
+const clean = (value) => {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim().slice(0, PLACE_FIELD_MAX_CHARS);
+    return trimmed === '' ? null : trimmed;
+};
+/**
+ * The three columns a row stores, from whatever a locator returned. Copies ONLY
+ * `country/region/city` — so a locator that returns extra fields (an `ip`, say) cannot get them
+ * written — and treats an empty or unknown country as no place at all.
+ */
+export function normalizePlace(place) {
+    const country = clean(place?.country);
+    if (!country || country.toUpperCase() === UNKNOWN_COUNTRY)
+        return { country: null, region: null, city: null };
+    return { country, region: clean(place?.region), city: clean(place?.city) };
+}
+/** Header values arrive percent-encoded when the edge had to (`cf-ipcity: S%C3%A3o%20Paulo`). */
+const header = (request, name) => {
+    const raw = request.headers.get(name);
+    if (raw == null)
+        return null;
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+};
+/** The edge's own answer: `request.cf` on a Worker, the `cf-*` headers behind the tunnel, else `null`. */
+export const locateFromCloudflare = (request) => {
+    const cf = request.cf;
+    if (cf && typeof cf.country === 'string') {
+        return { country: cf.country, region: clean(cf.region), city: clean(cf.city) };
+    }
+    const country = header(request, 'cf-ipcountry');
+    if (!country)
+        return null;
+    return { country, region: header(request, 'cf-region'), city: header(request, 'cf-ipcity') };
+};
+/** Run a locator the way the logger must: a throw is an unplaced request, never a failed one. */
+export function placeOf(locate, request) {
+    try {
+        return normalizePlace(locate(request));
+    }
+    catch {
+        return normalizePlace(null);
+    }
+}

package/dist/server/metrics/telemetrySink.d.ts

@@ -91,8 +91,13 @@ export interface TelemetrySinkOptions {
  * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
  * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
  * double1 = status          double2 = durationMs             double3 = bytesOut
+ * blob4   = country         blob5  = region                  blob6  = city        (v2, 4.23.0)
  * ```
  *
+ * v2 APPENDED blob4–6: where the request came from, as a place and never an address
+ * (`./requestPlace.ts`). `''` when unplaced, like `userId`. A v1 query never reads past blob3,
+ * so it is unaffected; a query written against v2 reads `''` on points written before it.
+ *
  * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
  * column, so sending ours would store the same instant twice.
  *
@@ -100,7 +105,7 @@ export interface TelemetrySinkOptions {
  * doubles array cannot hold a null and `0` is a real value for every one of them
  * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
  */
-export declare const TELEMETRY_POINT_VERSION = 1;
+export declare const TELEMETRY_POINT_VERSION = 2;
 /** The documented layout above, as data. Exported so the spec asserts the wire format itself. */
 export declare function toDataPoint(event: TelemetryEvent): {
     indexes: string[];

package/dist/server/metrics/telemetrySink.js

@@ -8,8 +8,13 @@ import { createMetricsBuffer } from './metricsBuffer.js';
  * index1  = route, truncated to 96 bytes  — the sampling key, so sampling is per route
  * blob1   = method          blob2  = route (untruncated)     blob3  = userId ('' when anonymous)
  * double1 = status          double2 = durationMs             double3 = bytesOut
+ * blob4   = country         blob5  = region                  blob6  = city        (v2, 4.23.0)
  * ```
  *
+ * v2 APPENDED blob4–6: where the request came from, as a place and never an address
+ * (`./requestPlace.ts`). `''` when unplaced, like `userId`. A v1 query never reads past blob3,
+ * so it is unaffected; a query written against v2 reads `''` on points written before it.
+ *
  * `ts` is deliberately absent: Analytics Engine stamps its own `timestamp`
  * column, so sending ours would store the same instant twice.
  *
@@ -17,7 +22,7 @@ import { createMetricsBuffer } from './metricsBuffer.js';
  * doubles array cannot hold a null and `0` is a real value for every one of them
  * (a 0-byte 204, notably). Read it as `NULL`, not as a measurement.
  */
-export const TELEMETRY_POINT_VERSION = 1;
+export const TELEMETRY_POINT_VERSION = 2;
 const INDEX_MAX_BYTES = 96;
 /**
  * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point —
@@ -38,7 +43,14 @@ export function toDataPoint(event) {
     const route = event.route ?? '';
     return {
         indexes: [truncateUtf8(route, INDEX_MAX_BYTES)],
-        blobs: [event.method ?? '', route, event.userId ?? ''],
+        blobs: [
+            event.method ?? '',
+            route,
+            event.userId ?? '',
+            event.country ?? '',
+            event.region ?? '',
+            event.city ?? '',
+        ],
         doubles: [num(event.status), num(event.durationMs), num(event.bytesOut)],
     };
 }

package/dist/server/middleware/requestLogger.d.ts

@@ -3,6 +3,7 @@ import type { MiddlewareHandler } from 'hono';
 import type { CursedbeltEnv } from '../context.js';
 import type { MetricsBuffer } from '../metrics/metricsBuffer.js';
 import { type AnalyticsEngineDataset, type TelemetrySink } from '../metrics/telemetrySink.js';
+import { type RequestLocator } from '../metrics/requestPlace.js';
 /**
  * Structured request/response logging. After each request it records one
  * telemetry event through the {@link TelemetrySink} (off the hot path) and, for
@@ -33,6 +34,13 @@ export interface RequestLoggerOpts {
     sink?: TelemetrySink;
     /** @deprecated Use {@link RequestLoggerOpts.sink} — a `MetricsBuffer` is one. Kept for callers that predate the sink. */
     buffer?: MetricsBuffer;
+    /**
+     * Where the request came from — returns a PLACE (`{ country, region?, city? }`) or `null`,
+     * never an address; the raw IP is not stored anywhere (`../metrics/requestPlace.ts`).
+     * Default: {@link locateFromCloudflare} — `request.cf` on a Worker, the `cf-ipcountry`
+     * header behind the tunnel. A throw is caught and the request recorded unplaced.
+     */
+    locate?: RequestLocator;
     /** Duration (ms) at/above which a 2xx request also logs an `event_logs` row. Default: 2000. */
     slowMs?: number;
     /** Also write `event_logs` rows for status ≥ 400. Default: true. */

package/dist/server/middleware/requestLogger.js

@@ -2,6 +2,7 @@ import { HTTPException } from 'hono/http-exception';
 import { isApiError } from '../errors.js';
 import { normalizeRoute } from '../metrics/normalizeRoute.js';
 import { createTelemetrySink, } from '../metrics/telemetrySink.js';
+import { locateFromCloudflare, placeOf } from '../metrics/requestPlace.js';
 function statusOfThrown(err) {
     if (isApiError(err))
         return err.status;
@@ -20,6 +21,7 @@ export function requestLogger(db, opts = {}) {
     const sink = opts.sink ?? opts.buffer ?? createTelemetrySink({ db, analytics: opts.analytics ?? null });
     const slowMs = opts.slowMs ?? 2000;
     const logErrors = opts.logErrors ?? true;
+    const locate = opts.locate ?? locateFromCloudflare;
     const insertEvent = db
         ? db.prepare(`INSERT INTO event_logs
        (id, correlation_id, event_name, type, message, details, duration_ms, user_id, created_at)
@@ -42,7 +44,8 @@ export function requestLogger(db, opts = {}) {
         const lenHeader = didThrow ? null : c.res.headers.get('content-length');
         const bytesOut = lenHeader ? Number(lenHeader) : null;
         const userId = c.get('userId') ?? null;
-        sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId });
+        const place = placeOf(locate, c.req.raw);
+        sink.record({ ts: Date.now(), method, route, status, durationMs, bytesOut, userId, ...place });
         const isError = status >= 400;
         const isSlow = durationMs >= slowMs;
         if (insertEvent && ((logErrors && isError) || isSlow)) {

package/dist/server/requestLog/requestMetrics.d.ts

@@ -60,6 +60,7 @@
  */
 import { Database } from "bun:sqlite";
 import type { MiddlewareHandler } from "hono";
+import type { RequestLocator } from "../metrics/requestPlace.js";
 import { type TelemetrySink } from "../metrics/telemetrySink.js";
 /** The file station reads, inside the app's data directory. */
 export declare const METRICS_DB = "metrics.sqlite";
@@ -80,12 +81,20 @@ export interface RequestMetrics {
     /** Where an inherited corpus went at this boot, if one was found. */
     archived: string | null;
 }
+export interface RequestMetricsOptions {
+    /**
+     * Place each request (`{ country, region?, city? }` or `null`) — never an address; the raw IP
+     * is not stored. Default: the edge's own answer, `locateFromCloudflare` (the `cf-ipcountry`
+     * header every tunnelled request carries). station passes its DB-IP reader here.
+     */
+    locate?: RequestLocator;
+}
 /** Open the corpus in `dir` and build the logger that writes into it. */
-export declare function openRequestMetrics(dir: string): RequestMetrics;
+export declare function openRequestMetrics(dir: string, options?: RequestMetricsOptions): RequestMetrics;
 /**
  * The request log for a DEPLOYED instance, or null. Deployed means `APP_DATA_DIR`
  * is set (the launchd plist sets it) and no test runner is in charge. A dev shell
  * records nothing rather than appending a developer's clicks to the live corpus.
  * Never throws: a failure is one stderr line and an app that serves unmeasured.
  */
-export declare function openRequestMetricsFromEnv(name: string, env: NodeJS.ProcessEnv): RequestMetrics | null;
+export declare function openRequestMetricsFromEnv(name: string, env: NodeJS.ProcessEnv, options?: RequestMetricsOptions): RequestMetrics | null;

package/dist/server/requestLog/requestMetrics.js

@@ -62,6 +62,7 @@ import { Database } from "bun:sqlite";
 import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { applyCcPragmas } from "cwip/sqlite";
+import { PLACE_COLUMNS } from "../metrics/metricsBuffer.js";
 import { createTelemetrySink } from "../metrics/telemetrySink.js";
 import { requestLogger } from "../middleware/requestLogger.js";
 import { runMigrations } from "../migration/runner.js";
@@ -90,6 +91,20 @@ const REQUEST_METRICS_MIGRATIONS = [
             db.run("CREATE INDEX idx_request_metrics_ts ON request_metrics (ts)");
         },
     },
+    {
+        // 4.23.0, task 2123: where a request came from — a PLACE, never the address (no `ip`
+        // column, ever; `../metrics/requestPlace.ts`). Nullable, so every row written before
+        // this reads as unplaced. Idempotent beyond the runner's once-only record: a column
+        // already present (hand-added, or a half-applied copy of this step) is left alone.
+        name: "0002_request_place",
+        up(db) {
+            const have = new Set(db.query("PRAGMA table_info(request_metrics)").all().map((c) => c.name));
+            for (const column of PLACE_COLUMNS) {
+                if (!have.has(column))
+                    db.run(`ALTER TABLE request_metrics ADD COLUMN ${column} TEXT`);
+            }
+        },
+    },
 ];
 /** The `application_id` stamped in a SQLite file's header, or null when it has no header yet. */
 function headerApplicationId(path) {
@@ -145,7 +160,7 @@ function openMetricsDb(dir) {
     return { db, archived };
 }
 /** Open the corpus in `dir` and build the logger that writes into it. */
-export function openRequestMetrics(dir) {
+export function openRequestMetrics(dir, options = {}) {
     const { db, archived } = openMetricsDb(dir);
     const inner = createTelemetrySink({ db });
     // 🔴 No user id — see the header. Nulled here so no context value can reach the row.
@@ -158,7 +173,10 @@ export function openRequestMetrics(dir) {
         },
     };
     // `null` database: the logger writes through `sink` only, and no `event_logs`.
-    const middleware = requestLogger(null, { sink });
+    const middleware = requestLogger(null, {
+        sink,
+        ...(options.locate ? { locate: options.locate } : {}),
+    });
     return { db, sink, middleware, archived };
 }
 /**
@@ -167,12 +185,12 @@ export function openRequestMetrics(dir) {
  * records nothing rather than appending a developer's clicks to the live corpus.
  * Never throws: a failure is one stderr line and an app that serves unmeasured.
  */
-export function openRequestMetricsFromEnv(name, env) {
+export function openRequestMetricsFromEnv(name, env, options = {}) {
     const dir = env.APP_DATA_DIR?.trim();
     if (!dir || isTestRuntime(env))
         return null;
     try {
-        const metrics = openRequestMetrics(dir);
+        const metrics = openRequestMetrics(dir, options);
         if (metrics.archived) {
             console.log(`[${name}] request metrics: archived the inherited corpus to ${metrics.archived}`);
         }

package/dist/server/telemetry.d.ts

@@ -17,3 +17,4 @@
  */
 export { type RequestLoggerOpts, requestLogger } from './middleware/requestLogger.js';
 export { type AnalyticsEngineDataset, createTelemetrySink, TELEMETRY_POINT_VERSION, type TelemetryEvent, type TelemetrySink, type TelemetrySinkOptions, toDataPoint, } from './metrics/telemetrySink.js';
+export { locateFromCloudflare, type RequestLocator, type RequestPlace, } from './metrics/requestPlace.js';

package/dist/server/telemetry.js

@@ -17,3 +17,4 @@
  */
 export { requestLogger } from './middleware/requestLogger.js';
 export { createTelemetrySink, TELEMETRY_POINT_VERSION, toDataPoint, } from './metrics/telemetrySink.js';
+export { locateFromCloudflare, } from './metrics/requestPlace.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.22.0",
+	"version": "4.23.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",

package/src/server/bench/budget.spec.ts

@@ -4,6 +4,7 @@ import {
   DEFAULT_ROUTE_CPU_BUDGET_MS,
   deriveCpuBudgetMs,
   MEASURED_FLEET_REQUESTS_PER_DAY,
+  MEASURED_WORKER_TRAFFIC,
   monthlyOverageUsd,
   OWNER_PROJECTED_REQUESTS_PER_DAY,
   resolveBudget,
@@ -64,6 +65,43 @@ describe('the derivation', () => {
   });
 });
 
+describe('the WORKER re-derivation (2026-09-23, task 083)', () => {
+  const W = MEASURED_WORKER_TRAFFIC;
+  const perDay = W.requests / W.days;
+  const edgeGatePerMonth = (W.edgeGateCpuMs / W.days) * DAYS_PER_MONTH;
+
+  it('the naive call over the whole account says 9.1 — below the default — and that is recorded, not hidden', () => {
+    expect(perDay).toBeCloseTo(108_001, 0);
+    const naive = deriveCpuBudgetMs({ requestsPerDay: perDay });
+    expect(naive).toBeCloseTo(9.13, 2);
+    expect(naive).toBeLessThan(DEFAULT_ROUTE_CPU_BUDGET_MS);
+    // …because 99.9 % of it is the edge gate, whose mean sits far under any route budget.
+    expect(W.edgeGateRequests / W.requests).toBeGreaterThan(0.998);
+    expect(W.edgeGateCpuMs / W.edgeGateRequests).toBeLessThan(DEFAULT_ROUTE_CPU_BUDGET_MS / 4);
+  });
+
+  it('🔴 the default stays under what an APP request may spend once the edge gate is set aside', () => {
+    const appAllowance = deriveCpuBudgetMs({
+      requestsPerDay: MEASURED_FLEET_REQUESTS_PER_DAY,
+      reservedCpuMsPerMonth: edgeGatePerMonth,
+    });
+    expect(appAllowance).toBeCloseTo(16.9, 1);
+    expect(DEFAULT_ROUTE_CPU_BUDGET_MS).toBeLessThanOrEqual(appAllowance);
+  });
+
+  it('and there is no evidence for tightening it: the account spends 30 % of its CPU allowance', () => {
+    const monthly = (W.cpuMs / W.days) * DAYS_PER_MONTH;
+    expect(monthly / WORKERS_PAID_INCLUDED_CPU_MS).toBeCloseTo(0.3, 2);
+  });
+
+  it('FAILURE PATH: a reservation that eats the allowance is refused, not turned into a negative budget', () => {
+    expect(() => deriveCpuBudgetMs({ reservedCpuMsPerMonth: WORKERS_PAID_INCLUDED_CPU_MS })).toThrow(
+      /reservedCpuMsPerMonth/,
+    );
+    expect(() => deriveCpuBudgetMs({ reservedCpuMsPerMonth: -1 })).toThrow(/reservedCpuMsPerMonth/);
+  });
+});
+
 describe('what going over actually costs', () => {
   it('prices the overage — 3× the CPU budget at this traffic is about $1.20/month', () => {
     const requestsPerMonth = OWNER_PROJECTED_REQUESTS_PER_DAY * DAYS_PER_MONTH;