cursedbelt-server 4.22.0 → 4.23.0

package/src/server/bench/budget.ts

@@ -82,6 +82,48 @@ export const DAYS_PER_MONTH = 30.4375;
  */
 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,
+} as const;
+
 /**
  * Derive the average CPU-ms a single request may spend before the fleet exceeds its
  * included CPU allowance.
@@ -99,9 +141,21 @@ export function deriveCpuBudgetMs(
     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 {
-  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;
@@ -136,6 +190,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;
 

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

@@ -23,11 +23,23 @@ import { BENCH_ORIGIN, runCpuBench } from './runBench.js';
  * timing would make the suite flaky for no extra truth.
  */
 
-/** Burn approximately `ms` of CPU. Deliberately un-optimizable: the result escapes. */
+/**
+ * Burn at least `ms` of CPU. Deliberately un-optimizable: the result escapes.
+ *
+ * 🔴 The deadline is on the CPU clock, not the wall clock. The recorder measures
+ * `process.cpuUsage`; a burner that stops at a WALL deadline hands it only the share of
+ * those milliseconds the scheduler granted, so under load (measured 2026-09-23, load 17 on
+ * 14 cores) a 12 ms burn read 5.5 CPU-ms and reddened `row.max > 6`. Spinning until the
+ * process has actually been charged `ms` makes every lower bound here hold at any load.
+ */
 function burnCpu(ms: number): number {
-  const deadline = performance.now() + ms;
+  const start = process.cpuUsage();
+  const spent = () => {
+    const d = process.cpuUsage(start);
+    return (d.user + d.system) / 1000;
+  };
   let acc = 0;
-  while (performance.now() < deadline) {
+  while (spent() < ms) {
     for (let i = 0; i < 2_000; i += 1) acc += Math.sqrt(i + acc % 7);
   }
   return acc;

package/src/server/bench/index.ts

@@ -50,6 +50,7 @@ export {
   deriveCpuBudgetMs,
   isExemption,
   MEASURED_FLEET_REQUESTS_PER_DAY,
+  MEASURED_WORKER_TRAFFIC,
   monthlyOverageUsd,
   OWNER_PROJECTED_REQUESTS_PER_DAY,
   type ResolvedBudget,

package/src/server/metrics/metricsBuffer.ts

@@ -20,8 +20,19 @@ 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 const PLACE_COLUMNS = ['country', 'region', 'city'] as const;
+
 export interface MetricsBufferOptions {
   db: Database;
   /** Flush cadence in ms. Default: 1500. */
@@ -45,9 +56,17 @@ export function createMetricsBuffer(opts: MetricsBufferOptions): MetricsBuffer {
   const { db, flushIntervalMs = 1500, maxSize = 5000 } = opts;
   let buffer: MetricRow[] = [];
 
+  // 🔴 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() as Array<{ name: string }>).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 (id, ts, method, route, status, duration_ms, bytes_out, user_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    `INSERT INTO request_metrics (${columns.join(', ')})
+     VALUES (${columns.map(() => '?').join(', ')})`,
   );
   const insertMany = db.transaction((rows: MetricRow[]) => {
     for (const r of rows) {
@@ -60,6 +79,7 @@ export function createMetricsBuffer(opts: MetricsBufferOptions): MetricsBuffer {
         r.durationMs,
         r.bytesOut,
         r.userId,
+        ...place.map((c) => r[c] ?? null),
       );
     }
   });

package/src/server/metrics/requestPlace.spec.ts

@@ -0,0 +1,142 @@
+import { Database } from 'bun:sqlite';
+import { describe, expect, it } from 'bun:test';
+import { Hono } from 'hono';
+import { requestLogger } from '../middleware/requestLogger.js';
+import { createMetricsBuffer } from './metricsBuffer.js';
+import { locateFromCloudflare, normalizePlace, PLACE_FIELD_MAX_CHARS, type RequestLocator } from './requestPlace.js';
+import { type AnalyticsEngineDataset, TELEMETRY_POINT_VERSION, toDataPoint } from './telemetrySink.js';
+
+/**
+ * Task 2123: a request is recorded with WHERE it came from — as a place, never as an address.
+ * Each claim here has its failure path beside it.
+ */
+
+type Point = Parameters<AnalyticsEngineDataset['writeDataPoint']>[0];
+const fakeDataset = () => {
+  const points: Point[] = [];
+  return { points, writeDataPoint: (p: Point) => void points.push(p) };
+};
+
+/** A Worker request: workerd hangs Cloudflare's geolocation off `request.cf`. */
+const workerRequest = (url: string, cf: Record<string, unknown>): Request => {
+  const request = new Request(url);
+  Object.defineProperty(request, 'cf', { value: cf });
+  return request;
+};
+
+const LEGACY_DDL = `CREATE TABLE request_metrics (
+  id TEXT PRIMARY KEY, ts INTEGER NOT NULL, method TEXT, route TEXT,
+  status INTEGER, duration_ms REAL, bytes_out INTEGER, user_id TEXT)`;
+const PLACED_DDL = LEGACY_DDL.replace('user_id TEXT)', 'user_id TEXT, country TEXT, region TEXT, city TEXT)');
+
+describe('normalizePlace — a place and nothing else', () => {
+  it('🔴 copies only country/region/city: an ip a locator returns can never be written', () => {
+    const leaky = { country: 'IE', city: 'Dublin', ip: '203.0.113.9' } as never;
+    const place = normalizePlace(leaky);
+    expect(place).toEqual({ country: 'IE', region: null, city: 'Dublin' });
+    expect(JSON.stringify(place)).not.toContain('203.0.113.9');
+  });
+
+  it("an unknown country ('XX', '', whitespace) is no place at all — region/city are dropped with it", () => {
+    for (const country of ['XX', 'xx', '', '   ']) {
+      expect(normalizePlace({ country, city: 'Nowhere' })).toEqual({ country: null, region: null, city: null });
+    }
+    expect(normalizePlace(null)).toEqual({ country: null, region: null, city: null });
+  });
+
+  it('caps each field so three of them cannot crowd the Analytics Engine blob budget', () => {
+    const place = normalizePlace({ country: 'US', city: 'x'.repeat(5000) });
+    expect(place.city?.length).toBe(PLACE_FIELD_MAX_CHARS);
+  });
+});
+
+describe('locateFromCloudflare — the default reads the edge', () => {
+  it('on a Worker: request.cf.country/region/city', () => {
+    const request = workerRequest('https://app.test/', { country: 'PT', region: 'Lisbon', city: 'Lisbon' });
+    expect(locateFromCloudflare(request)).toEqual({ country: 'PT', region: 'Lisbon', city: 'Lisbon' });
+  });
+
+  it('behind the tunnel: the cf-ipcountry header, and the finer headers when the zone sends them (percent-decoded)', () => {
+    const coarse = new Request('https://app.test/', { headers: { 'cf-ipcountry': 'BR' } });
+    expect(normalizePlace(locateFromCloudflare(coarse))).toEqual({ country: 'BR', region: null, city: null });
+    const fine = new Request('https://app.test/', {
+      headers: { 'cf-ipcountry': 'BR', 'cf-region': 'S%C3%A3o%20Paulo', 'cf-ipcity': 'S%C3%A3o%20Paulo' },
+    });
+    expect(locateFromCloudflare(fine)).toEqual({ country: 'BR', region: 'São Paulo', city: 'São Paulo' });
+  });
+
+  it('FAILURE PATH: a direct request (dev, tests) is unplaced, not invented', () => {
+    expect(locateFromCloudflare(new Request('http://localhost/'))).toBeNull();
+  });
+});
+
+describe('the Analytics Engine wire format — v2 appends the place at blob4–6', () => {
+  it('toDataPoint puts country/region/city in blob4/5/6 and leaves blob1–3 where they were', () => {
+    expect(TELEMETRY_POINT_VERSION).toBe(2);
+    const { blobs } = toDataPoint({
+      ts: 1, method: 'GET', route: '/', status: 200, durationMs: 1, bytesOut: 0, userId: 'u',
+      country: 'JP', region: 'Tokyo', city: 'Shibuya',
+    });
+    expect(blobs).toEqual(['GET', '/', 'u', 'JP', 'Tokyo', 'Shibuya']);
+  });
+
+  it('a Worker request is placed from request.cf with no app code at all', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(null, { analytics: ae }));
+    app.get('/', (c) => c.text('ok'));
+    await app.fetch(workerRequest('https://app.test/', { country: 'NZ', city: 'Wellington' }));
+    expect(ae.points[0].blobs?.slice(3)).toEqual(['NZ', '', 'Wellington']);
+  });
+
+  it('FAILURE PATH: a request the edge could not place writes empty place blobs, not a missing position', async () => {
+    const ae = fakeDataset();
+    const app = new Hono();
+    app.use('*', requestLogger(null, { analytics: ae }));
+    app.get('/', (c) => c.text('ok'));
+    await app.fetch(new Request('https://app.test/'));
+    expect(ae.points[0].blobs).toHaveLength(6);
+    expect(ae.points[0].blobs?.slice(3)).toEqual(['', '', '']);
+  });
+});
+
+describe('the SQLite sink — place columns where the table has them', () => {
+  const serve = async (db: Database, locate?: RequestLocator, request = new Request('http://app.test/x')) => {
+    const buffer = createMetricsBuffer({ db });
+    const app = new Hono();
+    app.use('*', requestLogger(null, { sink: buffer, ...(locate ? { locate } : {}) }));
+    app.get('/x', (c) => c.text('ok'));
+    expect((await app.fetch(request)).status).toBe(200);
+    buffer.stop();
+    return db.query('SELECT * FROM request_metrics').all() as Record<string, unknown>[];
+  };
+
+  it("an app's locate hook gets the Request and its place lands in country/region/city", async () => {
+    const db = new Database(':memory:');
+    db.run(PLACED_DDL);
+    let seen: Request | null = null;
+    const rows = await serve(db, (request) => {
+      seen = request;
+      return { country: 'IE', region: 'Leinster', city: 'Dublin' };
+    });
+    expect(seen).toBeInstanceOf(Request);
+    expect(rows).toEqual([expect.objectContaining({ route: '/x', country: 'IE', region: 'Leinster', city: 'Dublin' })]);
+  });
+
+  it('a locate that THROWS records the request unplaced — it never fails the request or loses the row', async () => {
+    const db = new Database(':memory:');
+    db.run(PLACED_DDL);
+    const rows = await serve(db, () => {
+      throw new Error('snapshot missing');
+    });
+    expect(rows).toEqual([expect.objectContaining({ route: '/x', status: 200, country: null, region: null, city: null })]);
+  });
+
+  it("🔴 a table created by an app's OWN older DDL (no place columns) keeps working after the bump", async () => {
+    const db = new Database(':memory:');
+    db.run(LEGACY_DDL);
+    const rows = await serve(db, () => ({ country: 'IE' }));
+    expect(rows).toHaveLength(1);
+    expect(Object.keys(rows[0])).not.toContain('country');
+  });
+});

package/src/server/metrics/requestPlace.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 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: unknown): string | null => {
+	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: RequestPlace | null | undefined): {
+	country: string | null;
+	region: string | null;
+	city: string | null;
+} {
+	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: Request, name: string): string | null => {
+	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: RequestLocator = (request) => {
+	const cf = (request as Request & { cf?: Record<string, unknown> }).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: RequestLocator, request: Request): ReturnType<typeof normalizePlace> {
+	try {
+		return normalizePlace(locate(request));
+	} catch {
+		return normalizePlace(null);
+	}
+}

package/src/server/metrics/telemetrySink.spec.ts

@@ -145,7 +145,8 @@ describe('toDataPoint — the layout is a wire format', () => {
       }),
     ).toEqual({
       indexes: ['/api/v1/sync/requested'],
-      blobs: ['POST', '/api/v1/sync/requested', 'u-1'],
+      // blob4–6 (v2) are the place; '' when unplaced, never a null hole.
+      blobs: ['POST', '/api/v1/sync/requested', 'u-1', '', '', ''],
       // bytesOut null → -1. `0` is a real value for a 204, so it cannot be the marker.
       doubles: [204, 12.5, -1],
     });

package/src/server/metrics/telemetrySink.ts

@@ -97,8 +97,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.
  *
@@ -106,7 +111,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 const TELEMETRY_POINT_VERSION = 1;
+export const TELEMETRY_POINT_VERSION = 2;
 
 const INDEX_MAX_BYTES = 96;
 
@@ -137,7 +142,14 @@ export function toDataPoint(event: TelemetryEvent): {
   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/src/server/middleware/requestLogger.ts

@@ -10,6 +10,7 @@ import {
   createTelemetrySink,
   type TelemetrySink,
 } from '../metrics/telemetrySink.js';
+import { locateFromCloudflare, placeOf, type RequestLocator } from '../metrics/requestPlace.js';
 
 /**
  * Structured request/response logging. After each request it records one
@@ -42,6 +43,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. */
@@ -69,6 +77,7 @@ export function requestLogger(
     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(
@@ -96,7 +105,9 @@ export function requestLogger(
     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;

package/src/server/requestLog/requestMetrics.spec.ts

@@ -204,3 +204,76 @@ describe("🔴 the inherited corpus is archived, never written", () => {
 		expect(readFileSync(join(dir, `${RETIRED_METRICS_DB}-wal`), "utf8")).toBe("moved already");
 	});
 });
+
+describe("0002_request_place — where a request came from, never its address (task 2123)", () => {
+	const placed = (path = join(dir, METRICS_DB)) => {
+		const db = new Database(path, { readonly: true });
+		try {
+			return db.query("SELECT route, country, region, city FROM request_metrics ORDER BY ts").all();
+		} finally {
+			db.close();
+		}
+	};
+
+	test("a fresh corpus has nullable country/region/city and 🔴 no ip column", () => {
+		const m = track(openRequestMetrics(dir));
+		const columns = (m.db.query("PRAGMA table_info(request_metrics)").all() as { name: string; notnull: number }[]);
+		const byName = new Map(columns.map((c) => [c.name, c]));
+		for (const c of ["country", "region", "city"]) expect(byName.get(c)?.notnull).toBe(0);
+		expect(byName.has("ip")).toBe(false);
+		expect(JSON.stringify(m.db.query("SELECT name FROM _migrations").all())).toContain("0002_request_place");
+	});
+
+	test("a live corpus from before 0002 is UPGRADED in place — not archived, its rows kept and read as unplaced", async () => {
+		// Exactly what 4.21/4.22 left on disk: application_id stamped, 0001 applied, rows in it.
+		const first = track(openRequestMetrics(dir));
+		first.db.run("ALTER TABLE request_metrics DROP COLUMN country");
+		first.db.run("ALTER TABLE request_metrics DROP COLUMN region");
+		first.db.run("ALTER TABLE request_metrics DROP COLUMN city");
+		first.db.run("DELETE FROM _migrations WHERE name = '0002_request_place'");
+		first.db.run("INSERT INTO request_metrics (id, ts, method, route, status) VALUES ('old', 1, 'GET', '/before', 200)");
+		first.sink.stop();
+		first.db.close();
+		opened.splice(opened.indexOf(first), 1);
+
+		const second = track(openRequestMetrics(dir, { locate: () => ({ country: "IE", city: "Dublin" }) }));
+		expect(second.archived).toBeNull();
+		await appOver(second).fetch(new Request("http://app.test/healthz"));
+		second.sink.flush();
+		expect(placed()).toEqual([
+			{ route: "/before", country: null, region: null, city: null },
+			{ route: "/healthz", country: "IE", region: null, city: "Dublin" },
+		]);
+	});
+
+	test("idempotent: a column already there (hand-added) is left alone and the step still records", () => {
+		const db = new Database(join(dir, METRICS_DB), { create: true });
+		db.run(`CREATE TABLE request_metrics (id TEXT PRIMARY KEY, ts INTEGER NOT NULL, method TEXT, route TEXT,
+			status INTEGER, duration_ms REAL, bytes_out INTEGER, user_id TEXT, country TEXT)`);
+		db.run(`PRAGMA application_id = ${0x4346524d}`); // the writer's marker, stamped after page 1 exists
+		db.run("CREATE TABLE _migrations (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)");
+		db.run("INSERT INTO _migrations VALUES ('0001_request_metrics', 'x')");
+		db.close();
+		const m = track(openRequestMetrics(dir));
+		expect(m.archived).toBeNull();
+		const names = (m.db.query("PRAGMA table_info(request_metrics)").all() as { name: string }[]).map((c) => c.name);
+		expect(names.filter((n) => n === "country")).toHaveLength(1);
+		expect(names).toEqual(expect.arrayContaining(["region", "city"]));
+	});
+
+	test("the default places a tunnelled request by its cf-ipcountry header; a direct one is unplaced", async () => {
+		const m = track(openRequestMetrics(dir));
+		const app = appOver(m);
+		await app.fetch(new Request("http://app.test/healthz", { headers: { "cf-ipcountry": "CA" } }));
+		await app.fetch(new Request("http://app.test/healthz"));
+		m.sink.flush();
+		expect(placed().map((r) => (r as { country: string | null }).country)).toEqual(["CA", null]);
+	});
+
+	test("openRequestMetricsFromEnv passes the locator through", async () => {
+		const m = track(openRequestMetricsFromEnv("app", { APP_DATA_DIR: dir }, { locate: () => ({ country: "FR" }) }));
+		await appOver(m).fetch(new Request("http://app.test/healthz"));
+		m.sink.flush();
+		expect(placed()).toEqual([{ route: "/healthz", country: "FR", region: null, city: null }]);
+	});
+});

package/src/server/requestLog/requestMetrics.ts

@@ -63,6 +63,8 @@ import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statS
 import { join } from "node:path";
 import { applyCcPragmas } from "cwip/sqlite";
 import type { MiddlewareHandler } from "hono";
+import { PLACE_COLUMNS } from "../metrics/metricsBuffer.js";
+import type { RequestLocator } from "../metrics/requestPlace.js";
 import { createTelemetrySink, type TelemetrySink } from "../metrics/telemetrySink.js";
 import { requestLogger } from "../middleware/requestLogger.js";
 import { runMigrations } from "../migration/runner.js";
@@ -97,6 +99,21 @@ const REQUEST_METRICS_MIGRATIONS: readonly Migration[] = [
 			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() as { name: string }[]).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. */
@@ -161,8 +178,17 @@ export interface RequestMetrics {
 	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 function openRequestMetrics(dir: string): RequestMetrics {
+export function openRequestMetrics(dir: string, options: RequestMetricsOptions = {}): RequestMetrics {
 	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.
@@ -175,7 +201,10 @@ export function openRequestMetrics(dir: string): RequestMetrics {
 		},
 	};
 	// `null` database: the logger writes through `sink` only, and no `event_logs`.
-	const middleware = requestLogger(null, { sink }) as unknown as MiddlewareHandler;
+	const middleware = requestLogger(null, {
+		sink,
+		...(options.locate ? { locate: options.locate } : {}),
+	}) as unknown as MiddlewareHandler;
 	return { db, sink, middleware, archived };
 }
 
@@ -185,11 +214,15 @@ export function openRequestMetrics(dir: string): RequestMetrics {
  * 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: string, env: NodeJS.ProcessEnv): RequestMetrics | null {
+export function openRequestMetricsFromEnv(
+	name: string,
+	env: NodeJS.ProcessEnv,
+	options: RequestMetricsOptions = {},
+): RequestMetrics | null {
 	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/src/server/telemetry.ts

@@ -25,3 +25,8 @@ export {
 	type TelemetrySinkOptions,
 	toDataPoint,
 } from './metrics/telemetrySink.js';
+export {
+	locateFromCloudflare,
+	type RequestLocator,
+	type RequestPlace,
+} from './metrics/requestPlace.js';