cursedbelt-server 4.22.0 → 4.24.0

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';

package/src/server/telemetryIsWorkerSafe.spec.ts

@@ -43,6 +43,23 @@ describe('🔴 cursedbelt-server/password — a Worker can import it (task 2129)
 	});
 });
 
+describe('🔴 cursedbelt-server/worker-argon2 — it exists to be imported by a Worker', () => {
+	test('reaches no `bun:` module at runtime; `Bun.file` is touched only on the Bun-only path branch', () => {
+		const { files, bunImports } = runtimeGraph(join(import.meta.dir, 'worker-argon2', 'index.ts'));
+		expect(bunImports).toEqual([]);
+		// Not vacuous: the loader and the shim are both in the graph.
+		expect(files.some((f) => f.endsWith('worker-argon2/argon2.ts'))).toBe(true);
+		expect(files.some((f) => f.endsWith('worker-argon2/password.ts'))).toBe(true);
+	});
+
+	test("its export map's `import` is the real module, not the Bun-only refusal", () => {
+		const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as {
+			exports: Record<string, { import?: string }>;
+		};
+		expect(pkg.exports['./worker-argon2']?.import).toBe('./dist/server/worker-argon2/index.js');
+	});
+});
+
 describe('cursedbelt-server/telemetry', () => {
 	test('🔴 reaches no `bun:` module at runtime — a Worker can import it', () => {
 		const { files, bunImports } = runtimeGraph(join(import.meta.dir, 'telemetry.ts'));

package/src/server/worker-argon2/argon2.ts

@@ -0,0 +1,85 @@
+/**
+ * argon2id as WebAssembly the Worker was HANDED, never WebAssembly it compiles.
+ *
+ * ## 🔴 Why this file exists: one unlock was 8.5–15 seconds of billed CPU
+ *
+ * `collections` averaged **489 CPU-ms per request on 2026-09-22 with a 15.2 s p99** (Cloudflare
+ * GraphQL, `workersInvocationsAdaptive`). Every second of it was `POST /__lock/unlock`: a real
+ * `wrangler tail` of the stage walk on 2026-09-23 read **8,519 CPU-ms and 10.4 s wall** for that
+ * one request and 10–38 ms for each of the other eleven. The lock verifies every account's
+ * argon2id hash (no early exit — `cursedbelt-server/master-lock` explains the timing oracle) plus
+ * a timing equalizer, so production's two accounts are three to four derivations per unlock, and
+ * `@noble/hashes`' pure-JS argon2id costs ~2.8 s each on workerd — five times the 562 ms it
+ * costs on this Mac. The owner waited ten seconds at the lock page, and a third account would
+ * have put the unlock within reach of the Worker's 30 s CPU ceiling, where it is killed and
+ * reads as a wrong password.
+ *
+ * ## 🔴 Why this shape: workerd refuses to COMPILE WebAssembly, not to RUN it
+ *
+ * `hash-wasm` failed here on 2026-09-18 with `Wasm code generation disallowed by embedder`
+ * because it compiles bytes it carries inline (`./password.ts` has the whole story). A
+ * `.wasm` file that is a STATIC import is different: wrangler bundles it as a
+ * `CompiledWasm` module and the runtime hands this code a ready `WebAssembly.Module`, which
+ * `WebAssembly.instantiate(module, imports)` may instantiate. `argon2id` (openpgpjs, MIT) ships
+ * its two binaries as plain files and lets the caller do the instantiating, which is exactly the
+ * seam a Worker needs. Its default entry inlines base64 and compiles it — so it is never imported.
+ *
+ * Under Bun (every test, and the Mac) the same import is a PATH STRING, so the bytes are read
+ * and compiled here — which Bun allows. `index.spec.ts` drives the Worker's branch too, with
+ * `WebAssembly.compile` made to throw exactly as workerd throws.
+ *
+ * ## Why it lives in `cursedbelt-server` (4.24.0)
+ *
+ * It was born in `apps/collections/worker/argon2.ts` (commit 7996ded) while `apps/vault` and
+ * `apps/patterns` still carried the pure-JS copy, so every sign-in there billed seconds. One copy
+ * here, `argon2id` a pinned dependency of this package: its two `.wasm` files ship in its own
+ * `files`, and wrangler — which resolves this subpath's `import` condition, `dist/…/argon2.js`,
+ * where tsc leaves the bare `argon2id/dist/*.wasm` specifiers untouched — bundles them from
+ * `node_modules` as `CompiledWasm`. `index.spec.ts` asserts `dist` still carries them that way.
+ */
+import noSimdWasm from "argon2id/dist/no-simd.wasm";
+import simdWasm from "argon2id/dist/simd.wasm";
+import setupWasm, { type computeHash } from "argon2id/lib/setup.js";
+
+/** What a `.wasm` import is: a compiled module under wrangler, a file path under Bun. */
+export type WasmImport = WebAssembly.Module | string;
+
+/**
+ * Turn one `.wasm` import into an instance. 🔴 A `Module` is instantiated and NEVER compiled —
+ * that is the whole workerd rule — and only a path (Bun) is read and compiled.
+ */
+export async function instantiateWasm(
+	source: WasmImport,
+	imports: WebAssembly.Imports,
+): Promise<WebAssembly.WebAssemblyInstantiatedSource> {
+	const module =
+		typeof source === "string" ? await WebAssembly.compile(await Bun.file(source).arrayBuffer()) : source;
+	const instance = await WebAssembly.instantiate(module, imports);
+	return { module, instance };
+}
+
+/** Build a hasher from the two binaries — SIMD first, the plain one if SIMD will not load. */
+export function loadArgon2(simd: WasmImport = simdWasm, noSimd: WasmImport = noSimdWasm): Promise<computeHash> {
+	return setupWasm(
+		(imports) => instantiateWasm(simd, imports),
+		(imports) => instantiateWasm(noSimd, imports),
+	);
+}
+
+/*
+ * 🔴 ONE hasher per isolate, built on first use. Not request state — it holds no password and no
+ * result between calls (the library clears its memory after each) — so this is the one kind of
+ * module-scope value a Worker may keep. The reason to keep it is MEMORY: each
+ * instance owns a 65 MB `WebAssembly.Memory` that can never shrink, and an unlock runs three or
+ * four derivations back to back; one per call would stack up to four of them against a 128 MB
+ * isolate before a collector ran. A load that FAILS is not cached, so the next unlock retries.
+ */
+let shared: Promise<computeHash> | null = null;
+
+export function argon2(): Promise<computeHash> {
+	shared ??= loadArgon2().catch((error: unknown) => {
+		shared = null;
+		throw error;
+	});
+	return shared;
+}