cursedbelt-server 4.20.0 → 4.21.0

package/README.md

@@ -36,6 +36,7 @@ actually keeps.
 | `./guard/revocations` | — | `bun:sqlite` |
 | `./sqlite` | — | `bun:sqlite` |
 | `./engagement` | — | `bun:sqlite` |
+| `./request-log` | — | `bun:sqlite` |
 
 `sharp` and `@node-rs/argon2` are loaded lazily (`await import()`), so a missing one breaks only
 the feature that asks for it, not the build.

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

@@ -0,0 +1,91 @@
+/**
+ * `cursedbelt-server/request-log` — the request log, "is this app healthy": one row per request
+ * served, in `<APP_DATA_DIR>/metrics.sqlite`, the file station's Metrics page reads for every app on
+ * this Mac (`apps/station/src/server/fleetMetrics.ts`, `METRICS_DB`).
+ *
+ * ── Why it is here (4.21.0) ─────────────────────────────────────────────────
+ * `apps/family` and `apps/roms` held this module byte-identically (task 265's rollout), and
+ * `check-copies` counted it as five copy groups. The API, the header marker and the migration name
+ * are exactly the apps' — a live corpus is recognised by `METRICS_APPLICATION_ID` and by the
+ * `0001_request_metrics` row in its migrations table, so changing either would make every
+ * existing `metrics.sqlite` look inherited and archive it. Bun-only (`bun:sqlite`, `node:fs`): under
+ * Node the export map routes this subpath to `_bunOnly.js`, the way `./engagement` does; it is NOT
+ * part of `./telemetry`, which is Worker-safe (`telemetryIsWorkerSafe.spec.ts`).
+ *
+ * ── Why it came back, 2026-09-23 (task 265) ─────────────────────────────────
+ * `serve.ts` once recorded that request metrics were GONE, on the grounds that the
+ * console that read them was in the retired generation. Station reads them now, and
+ * a measurement found that all eight apps recorded nothing while their
+ * `metrics.sqlite` files — the RETIRED instances' history, inherited at graduation —
+ * rendered as a corpus that had simply gone quiet. This mounts `cursedbelt-server`'s
+ * own seam (`requestLogger` through `createTelemetrySink`, the modules the Worker-safe
+ * `cursedbelt-server/telemetry` leaf re-exports).
+ *
+ * ── 🔴 The inherited file is ARCHIVED, never written ────────────────────────
+ * The file already at `metrics.sqlite` on the live machine is a previous
+ * generation's history under a different schema (`id INTEGER AUTOINCREMENT` plus
+ * `ip`/`country`/`city`/`device`/`form`; this writer inserts `id TEXT` plus
+ * `user_id`). Appending to it would make every future measurement unreadable, so
+ * {@link retireInheritedCorpus} runs at every boot, BEFORE the database is opened:
+ *
+ *   - a file that carries {@link METRICS_APPLICATION_ID} in its header is this
+ *     writer's own, and is left alone — so a second boot is a no-op;
+ *   - anything else is RENAMED, with its `-wal`/`-shm` sidecars, to
+ *     `metrics.retired.sqlite` — or `metrics.retired-2.sqlite`, `-3`, … when that
+ *     name is taken, so two inherited corpora are both kept and nothing is ever
+ *     overwritten. A rename touches no byte of the file, which is the point.
+ *
+ * The marker lives in the SQLite header (`PRAGMA application_id`, offset 68) so it
+ * can be read without opening the database — opening an inherited WAL database
+ * read-write would checkpoint into it on close, which IS writing into it. The
+ * migration checkpoints after stamping it, so the marker is on disk before the
+ * first request is recorded and a crash cannot leave a fresh corpus that the next
+ * boot mistakes for an inherited one.
+ *
+ * ── 🔴 No user id, ever ─────────────────────────────────────────────────────
+ * `cursedbelt-server/engagement`'s header states the split: `metrics/` promises it
+ * holds NO user id, in every app; `engagement.sqlite` is the user-keyed store. The
+ * writer's schema has a `user_id` column and `requestLogger` fills it from
+ * `c.get("userId")`, so the sink here nulls it on every event — whatever any future
+ * middleware puts on the context — and the logger is given no database of its own,
+ * which means it writes no `event_logs` rows either (those carry a `user_id` too,
+ * and nothing in this generation reads them).
+ *
+ * ── Never takes the app down ────────────────────────────────────────────────
+ * {@link openRequestMetricsFromEnv} catches everything and says so on stderr: an
+ * app that cannot record its traffic must still SERVE it. What catches an app that
+ * silently STOPS recording is `requestMetrics.test.ts`, which drives `/healthz`
+ * through a real server and fails when no row lands — `requestMetrics.spec.ts` here, and each
+ * app's own test through its own `createServer`.
+ */
+import { Database } from "bun:sqlite";
+import type { MiddlewareHandler } from "hono";
+import { type TelemetrySink } from "../metrics/telemetrySink.js";
+/** The file station reads, inside the app's data directory. */
+export declare const METRICS_DB = "metrics.sqlite";
+/** Where an inherited corpus is moved to — the first free of this and `metrics.retired-<n>.sqlite`. */
+export declare const RETIRED_METRICS_DB = "metrics.retired.sqlite";
+/**
+ * Move an inherited `metrics.sqlite` out of the way, or do nothing. Returns the
+ * path it was archived to, or null when there was nothing to archive. See the
+ * header: never writes a byte of the file, never overwrites anything, idempotent.
+ */
+export declare function retireInheritedCorpus(dir: string): string | null;
+export interface RequestMetrics {
+    db: Database;
+    /** Pending rows are flushed on a 1.5 s timer; `flush()` forces it (tests, shutdown). */
+    sink: TelemetrySink;
+    /** Register FIRST — ahead of every route it must see. */
+    middleware: MiddlewareHandler;
+    /** Where an inherited corpus went at this boot, if one was found. */
+    archived: string | null;
+}
+/** Open the corpus in `dir` and build the logger that writes into it. */
+export declare function openRequestMetrics(dir: string): 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;

package/dist/server/requestLog/requestMetrics.js

@@ -0,0 +1,185 @@
+/**
+ * `cursedbelt-server/request-log` — the request log, "is this app healthy": one row per request
+ * served, in `<APP_DATA_DIR>/metrics.sqlite`, the file station's Metrics page reads for every app on
+ * this Mac (`apps/station/src/server/fleetMetrics.ts`, `METRICS_DB`).
+ *
+ * ── Why it is here (4.21.0) ─────────────────────────────────────────────────
+ * `apps/family` and `apps/roms` held this module byte-identically (task 265's rollout), and
+ * `check-copies` counted it as five copy groups. The API, the header marker and the migration name
+ * are exactly the apps' — a live corpus is recognised by `METRICS_APPLICATION_ID` and by the
+ * `0001_request_metrics` row in its migrations table, so changing either would make every
+ * existing `metrics.sqlite` look inherited and archive it. Bun-only (`bun:sqlite`, `node:fs`): under
+ * Node the export map routes this subpath to `_bunOnly.js`, the way `./engagement` does; it is NOT
+ * part of `./telemetry`, which is Worker-safe (`telemetryIsWorkerSafe.spec.ts`).
+ *
+ * ── Why it came back, 2026-09-23 (task 265) ─────────────────────────────────
+ * `serve.ts` once recorded that request metrics were GONE, on the grounds that the
+ * console that read them was in the retired generation. Station reads them now, and
+ * a measurement found that all eight apps recorded nothing while their
+ * `metrics.sqlite` files — the RETIRED instances' history, inherited at graduation —
+ * rendered as a corpus that had simply gone quiet. This mounts `cursedbelt-server`'s
+ * own seam (`requestLogger` through `createTelemetrySink`, the modules the Worker-safe
+ * `cursedbelt-server/telemetry` leaf re-exports).
+ *
+ * ── 🔴 The inherited file is ARCHIVED, never written ────────────────────────
+ * The file already at `metrics.sqlite` on the live machine is a previous
+ * generation's history under a different schema (`id INTEGER AUTOINCREMENT` plus
+ * `ip`/`country`/`city`/`device`/`form`; this writer inserts `id TEXT` plus
+ * `user_id`). Appending to it would make every future measurement unreadable, so
+ * {@link retireInheritedCorpus} runs at every boot, BEFORE the database is opened:
+ *
+ *   - a file that carries {@link METRICS_APPLICATION_ID} in its header is this
+ *     writer's own, and is left alone — so a second boot is a no-op;
+ *   - anything else is RENAMED, with its `-wal`/`-shm` sidecars, to
+ *     `metrics.retired.sqlite` — or `metrics.retired-2.sqlite`, `-3`, … when that
+ *     name is taken, so two inherited corpora are both kept and nothing is ever
+ *     overwritten. A rename touches no byte of the file, which is the point.
+ *
+ * The marker lives in the SQLite header (`PRAGMA application_id`, offset 68) so it
+ * can be read without opening the database — opening an inherited WAL database
+ * read-write would checkpoint into it on close, which IS writing into it. The
+ * migration checkpoints after stamping it, so the marker is on disk before the
+ * first request is recorded and a crash cannot leave a fresh corpus that the next
+ * boot mistakes for an inherited one.
+ *
+ * ── 🔴 No user id, ever ─────────────────────────────────────────────────────
+ * `cursedbelt-server/engagement`'s header states the split: `metrics/` promises it
+ * holds NO user id, in every app; `engagement.sqlite` is the user-keyed store. The
+ * writer's schema has a `user_id` column and `requestLogger` fills it from
+ * `c.get("userId")`, so the sink here nulls it on every event — whatever any future
+ * middleware puts on the context — and the logger is given no database of its own,
+ * which means it writes no `event_logs` rows either (those carry a `user_id` too,
+ * and nothing in this generation reads them).
+ *
+ * ── Never takes the app down ────────────────────────────────────────────────
+ * {@link openRequestMetricsFromEnv} catches everything and says so on stderr: an
+ * app that cannot record its traffic must still SERVE it. What catches an app that
+ * silently STOPS recording is `requestMetrics.test.ts`, which drives `/healthz`
+ * through a real server and fails when no row lands — `requestMetrics.spec.ts` here, and each
+ * app's own test through its own `createServer`.
+ */
+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 { createTelemetrySink } from "../metrics/telemetrySink.js";
+import { requestLogger } from "../middleware/requestLogger.js";
+import { runMigrations } from "../migration/runner.js";
+import { isTestRuntime } from "../satellite/door.js";
+/** The file station reads, inside the app's data directory. */
+export const METRICS_DB = "metrics.sqlite";
+/** Where an inherited corpus is moved to — the first free of this and `metrics.retired-<n>.sqlite`. */
+export const RETIRED_METRICS_DB = "metrics.retired.sqlite";
+/** `PRAGMA application_id` of a corpus THIS writer created: "CFRM", cursedforge request metrics. */
+const METRICS_APPLICATION_ID = 0x4346524d;
+const SIDECARS = ["-wal", "-shm", "-journal"];
+/**
+ * The writer's own schema — the columns `cursedbelt-server`'s `metricsBuffer`
+ * inserts, and the ones station's reader asks for (`ts`, `method`, `route`,
+ * `status`, `duration_ms`, `bytes_out`). Append-only: a migration, once applied,
+ * never changes.
+ */
+const REQUEST_METRICS_MIGRATIONS = [
+    {
+        name: "0001_request_metrics",
+        up(db) {
+            db.run(`PRAGMA application_id = ${METRICS_APPLICATION_ID}`);
+            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)`);
+            db.run("CREATE INDEX idx_request_metrics_ts ON request_metrics (ts)");
+        },
+    },
+];
+/** The `application_id` stamped in a SQLite file's header, or null when it has no header yet. */
+function headerApplicationId(path) {
+    const fd = openSync(path, "r");
+    try {
+        const header = Buffer.alloc(72);
+        if (readSync(fd, header, 0, 72, 0) < 72)
+            return null;
+        return header.readUInt32BE(68);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+const sizeOf = (path) => (existsSync(path) ? statSync(path).size : 0);
+/**
+ * Move an inherited `metrics.sqlite` out of the way, or do nothing. Returns the
+ * path it was archived to, or null when there was nothing to archive. See the
+ * header: never writes a byte of the file, never overwrites anything, idempotent.
+ */
+export function retireInheritedCorpus(dir) {
+    const live = join(dir, METRICS_DB);
+    if (!existsSync(live))
+        return null;
+    // An empty file with no journal holds nothing — SQLite simply initialises it.
+    if (sizeOf(live) === 0 && SIDECARS.every((s) => sizeOf(live + s) === 0))
+        return null;
+    if (headerApplicationId(live) === METRICS_APPLICATION_ID)
+        return null;
+    const present = SIDECARS.filter((s) => existsSync(live + s));
+    let target = join(dir, RETIRED_METRICS_DB);
+    for (let n = 2; existsSync(target) || present.some((s) => existsSync(target + s)); n++) {
+        target = join(dir, RETIRED_METRICS_DB.replace(/\.sqlite$/, `-${n}.sqlite`));
+    }
+    // Sidecars FIRST, then the database: a crash between the two leaves the database
+    // where the next boot finds it again, and — because a moved sidecar is no longer
+    // at the source — the loop above picks this same `target`, so the pair is rejoined.
+    for (const s of present)
+        renameSync(live + s, target + s);
+    renameSync(live, target);
+    return target;
+}
+/** Retire any inherited corpus, then open (creating if need be) this writer's own. */
+function openMetricsDb(dir) {
+    mkdirSync(dir, { recursive: true });
+    const archived = retireInheritedCorpus(dir);
+    const db = new Database(join(dir, METRICS_DB), { create: true });
+    applyCcPragmas(db);
+    if (runMigrations(db, REQUEST_METRICS_MIGRATIONS).length > 0) {
+        // Put the header marker in the main file now, not at some later checkpoint.
+        db.run("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    return { db, archived };
+}
+/** Open the corpus in `dir` and build the logger that writes into it. */
+export function openRequestMetrics(dir) {
+    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.
+    const sink = {
+        record: (event) => inner.record({ ...event, userId: null }),
+        flush: () => inner.flush(),
+        stop: () => inner.stop(),
+        get size() {
+            return inner.size;
+        },
+    };
+    // `null` database: the logger writes through `sink` only, and no `event_logs`.
+    const middleware = requestLogger(null, { sink });
+    return { db, sink, middleware, archived };
+}
+/**
+ * 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 function openRequestMetricsFromEnv(name, env) {
+    const dir = env.APP_DATA_DIR?.trim();
+    if (!dir || isTestRuntime(env))
+        return null;
+    try {
+        const metrics = openRequestMetrics(dir);
+        if (metrics.archived) {
+            console.log(`[${name}] request metrics: archived the inherited corpus to ${metrics.archived}`);
+        }
+        return metrics;
+    }
+    catch (error) {
+        console.error(`[${name}] request metrics disabled: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}

package/dist/server/ws/hub.js

@@ -116,8 +116,13 @@ export function createWsHub(opts) {
                 const client = clientFromWs(ws);
                 if (!client)
                     return;
-                channelOf(client.channel)?.onDisconnect?.(client, hub);
+                // 🔴 Remove FIRST, then tell the channel. The recipe every presence app follows is
+                // "broadcast hub.getPresence(channel) from onDisconnect" (cursedbelt's usePresence doc),
+                // and until 4.20.1 this called onDisconnect while the leaver was still registered — so
+                // the roster it broadcast still listed the person who had just left. apps/roms deferred a
+                // microtask to work around it (src/server/presence.ts). hub.spec.ts pins the order.
                 clients.delete(client.id);
+                channelOf(client.channel)?.onDisconnect?.(client, hub);
             },
         },
         broadcast(channel, event, data) {

package/dist/server/ws/types.d.ts

@@ -61,7 +61,8 @@ export interface WsChannel<TMsg = WsMessage> {
     onConnect?(client: WsClient, hub: WsHub): void;
     /** Fired once per inbound frame (the parsed `{ event, data }` envelope). */
     onMessage(client: WsClient, msg: TMsg, hub: WsHub): void;
-    /** Fired when the socket closes (explicit, stale-culled, or peer-dropped). */
+    /** Fired when the socket closes (explicit, stale-culled, or peer-dropped) — AFTER the client is
+     *  removed, so `hub.getPresence()` here is the roster without it (4.20.1). */
     onDisconnect?(client: WsClient, hub: WsHub): void;
     /** Whether this channel contributes to {@link WsHub.getPresence}. Default: false. */
     presence?: boolean;

package/dist/subpathReach.js

@@ -55,4 +55,6 @@ export const MAY_NEED_BUN = {
     // The engagement store IS `engagement.sqlite` on the Mac (4.19.0, task 280) — the recorder
     // runs where the app's own database is. A Worker app records nothing until it has a D1 store.
     './engagement': ['bun:sqlite'],
+    // The request log IS `metrics.sqlite` beside the app's data (4.21.0) — a Mac-hosted server's.
+    './request-log': ['bun:sqlite'],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.20.0",
+	"version": "4.21.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.",
@@ -215,6 +215,12 @@
 			"source": "./src/server/auth/passwordCost.ts",
 			"import": "./dist/server/_bunOnly.js"
 		},
+		"./request-log": {
+			"types": "./dist/server/requestLog/requestMetrics.d.ts",
+			"bun": "./src/server/requestLog/requestMetrics.ts",
+			"source": "./src/server/requestLog/requestMetrics.ts",
+			"import": "./dist/server/_bunOnly.js"
+		},
 		"./notifications": {
 			"types": "./dist/server/notifications/index.d.ts",
 			"bun": "./src/server/notifications/index.ts",

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

@@ -0,0 +1,206 @@
+/**
+ * The request log's CHECK (task 265, step 4), lifted from apps/family + apps/roms with the module
+ * (4.21.0): a request through a real Hono app with the middleware mounted FIRST lands a row in
+ * `metrics.sqlite` — and the same app without it lands none, so the assertion can red. Each app
+ * keeps its own test through its own `createServer`; this one proves the library's half.
+ *
+ * Plus the two promises `requestMetrics.ts` makes: the inherited corpus is archived
+ * and never written, and no user id reaches a row.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	METRICS_DB,
+	openRequestMetrics,
+	openRequestMetricsFromEnv,
+	RETIRED_METRICS_DB,
+	type RequestMetrics,
+	retireInheritedCorpus,
+} from "./requestMetrics.js";
+import { Hono } from "hono";
+
+let dir: string;
+const opened: RequestMetrics[] = [];
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "cbs-request-metrics-"));
+});
+afterEach(() => {
+	for (const m of opened.splice(0)) {
+		m.sink.stop();
+		m.db.close();
+	}
+	rmSync(dir, { recursive: true });
+});
+
+const track = (m: RequestMetrics | null): RequestMetrics => {
+	if (!m) throw new Error("expected a request log");
+	opened.push(m);
+	return m;
+};
+
+/** What station reads: every row, oldest first. */
+function rows(path = join(dir, METRICS_DB)): Array<Record<string, unknown>> {
+	const db = new Database(path, { readonly: true });
+	try {
+		return db.query("SELECT method, route, status, bytes_out, user_id FROM request_metrics ORDER BY ts").all() as Array<
+			Record<string, unknown>
+		>;
+	} finally {
+		db.close();
+	}
+}
+
+/** The retired generation's schema, as `apps/station`'s fixture spells it. */
+function writeInheritedCorpus(path: string): void {
+	const db = new Database(path, { create: true });
+	db.run(`CREATE TABLE request_metrics (
+		id INTEGER PRIMARY KEY AUTOINCREMENT, ts INTEGER NOT NULL, method TEXT NOT NULL,
+		route TEXT NOT NULL, status INTEGER NOT NULL, duration_ms REAL NOT NULL,
+		bytes_out INTEGER NOT NULL DEFAULT 0, ip TEXT NOT NULL DEFAULT '', country TEXT NOT NULL DEFAULT '')`);
+	db.run("INSERT INTO request_metrics (ts, method, route, status, duration_ms) VALUES (1, 'GET', '/old', 200, 3)");
+	db.close();
+}
+
+/** A real Hono app: the logger mounted FIRST (as an app does), then its routes and a catch-all miss. */
+function appOver(metrics: RequestMetrics | null, mount?: (app: Hono) => void): Hono {
+	const app = new Hono();
+	if (metrics) app.use("*", metrics.middleware);
+	app.get("/healthz", (c) => c.json({ ok: true }));
+	mount?.(app);
+	app.all("*", (c) => c.text("not found", 404));
+	return app;
+}
+
+describe("the check: a request through a real app lands a row", () => {
+	test("GET /healthz lands one row in metrics.sqlite", async () => {
+		const metrics = track(openRequestMetrics(dir));
+		const app = appOver(metrics);
+		expect((await app.fetch(new Request("http://app.test/healthz"))).status).toBe(200);
+		metrics.sink.flush();
+
+		expect(rows()).toEqual([expect.objectContaining({ method: "GET", route: "/healthz", status: 200, user_id: null })]);
+	});
+
+	test("FAILURE PATH: without the logger the same request lands nothing — the check above can red", async () => {
+		const metrics = track(openRequestMetrics(dir));
+		const app = appOver(null);
+		expect((await app.fetch(new Request("http://app.test/healthz"))).status).toBe(200);
+		metrics.sink.flush();
+
+		expect(rows()).toEqual([]);
+	});
+
+	test("it sees every route: a parameterised route by its PATTERN, and a miss", async () => {
+		const metrics = track(openRequestMetrics(dir));
+		const app = appOver(metrics, (a) => a.get("/api/v1/thing/:id", (c) => c.json({ ok: true })));
+		await app.fetch(new Request("http://app.test/api/v1/thing/42"));
+		await app.fetch(new Request("http://app.test/assets/missing.js"));
+		metrics.sink.flush();
+
+		expect(rows().map((r) => `${r.route} ${r.status}`)).toEqual([
+			"/api/v1/thing/:id 200", // the PATTERN, never the id
+			"/assets/missing.js 404",
+		]);
+	});
+
+	test("🔴 no user id reaches a row, whatever a middleware puts on the context", async () => {
+		const metrics = track(openRequestMetrics(dir));
+		const app = appOver(metrics, (a) =>
+			a.get("/api/v1/me", (c) => {
+				c.set("userId" as never, "user-1" as never);
+				return c.json({ ok: true });
+			}),
+		);
+		await app.fetch(new Request("http://app.test/api/v1/me"));
+		metrics.sink.flush();
+
+		expect(rows()).toEqual([expect.objectContaining({ route: "/api/v1/me", user_id: null })]);
+	});
+});
+
+describe("openRequestMetricsFromEnv — what a deployed server calls at boot", () => {
+	test("a deployed instance (APP_DATA_DIR, no test runner) records; the inherited corpus is archived first", async () => {
+		writeInheritedCorpus(join(dir, METRICS_DB));
+		const metrics = track(openRequestMetricsFromEnv("app", { APP_DATA_DIR: dir }));
+		await appOver(metrics).fetch(new Request("http://app.test/healthz"));
+		metrics.sink.flush();
+
+		expect(metrics.archived).toBe(join(dir, RETIRED_METRICS_DB));
+		expect(rows()).toEqual([expect.objectContaining({ route: "/healthz", status: 200 })]);
+		// The retired history is intact and was not appended to.
+		const retired = new Database(join(dir, RETIRED_METRICS_DB), { readonly: true });
+		expect(retired.query("SELECT route FROM request_metrics").all()).toEqual([{ route: "/old" }]);
+		retired.close();
+	});
+
+	test("a test runner, or no APP_DATA_DIR, records nothing and creates no file", () => {
+		expect(openRequestMetricsFromEnv("app", { APP_DATA_DIR: dir, BUN_TEST: "1" })).toBeNull();
+		expect(openRequestMetricsFromEnv("app", {})).toBeNull();
+		expect(existsSync(join(dir, METRICS_DB))).toBe(false);
+	});
+
+	test("a directory it cannot open serves unmeasured instead of throwing", () => {
+		writeFileSync(join(dir, "not-a-dir"), "");
+		expect(openRequestMetricsFromEnv("app", { APP_DATA_DIR: join(dir, "not-a-dir") })).toBeNull();
+	});
+});
+
+describe("🔴 the live-corpus markers are the apps' own, byte for byte", () => {
+	test("application_id 0x4346524d and the 0001_request_metrics migration — or every live corpus reads as inherited", () => {
+		const m = track(openRequestMetrics(dir));
+		expect((m.db.query("PRAGMA application_id").get() as { application_id: number }).application_id).toBe(0x4346524d);
+		const names = JSON.stringify(m.db.query("SELECT * FROM sqlite_master WHERE type = 'table'").all());
+		expect(names).toContain("request_metrics");
+		const tables = (m.db.query("SELECT name FROM sqlite_master WHERE type = 'table'").all() as { name: string }[]).map((r) => r.name);
+		const migrationsTable = tables.find((n) => n !== "request_metrics" && n.toLowerCase().includes("migration"));
+		expect(migrationsTable, `no migrations table among ${tables.join(", ")}`).toBeDefined();
+		expect(JSON.stringify(m.db.query(`SELECT * FROM ${migrationsTable}`).all())).toContain("0001_request_metrics");
+	});
+});
+
+describe("🔴 the inherited corpus is archived, never written", () => {
+	test("a second boot leaves the writer's own corpus alone — even after a crash", () => {
+		const first = track(openRequestMetrics(dir));
+		expect(first.archived).toBeNull();
+		// Still OPEN, as if the process died here: the marker must already be on disk,
+		// or the next boot would archive this generation's own corpus.
+		expect(retireInheritedCorpus(dir)).toBeNull();
+		expect(existsSync(join(dir, RETIRED_METRICS_DB))).toBe(false);
+	});
+
+	test("the file moves byte-for-byte, WITH its sidecars", () => {
+		const live = join(dir, METRICS_DB);
+		writeInheritedCorpus(live);
+		writeFileSync(`${live}-wal`, "pending frames");
+		const before = readFileSync(live);
+
+		const target = retireInheritedCorpus(dir);
+		expect(target).toBe(join(dir, RETIRED_METRICS_DB));
+		expect(readFileSync(join(dir, RETIRED_METRICS_DB)).equals(before)).toBe(true);
+		expect(readFileSync(`${target}-wal`, "utf8")).toBe("pending frames");
+		expect(existsSync(live)).toBe(false);
+		expect(existsSync(`${live}-wal`)).toBe(false);
+	});
+
+	test("an archive already there is KEPT: the next inherited corpus takes the next free name", () => {
+		writeFileSync(join(dir, RETIRED_METRICS_DB), "the first archive");
+		writeInheritedCorpus(join(dir, METRICS_DB));
+
+		expect(retireInheritedCorpus(dir)).toBe(join(dir, "metrics.retired-2.sqlite"));
+		expect(readFileSync(join(dir, RETIRED_METRICS_DB), "utf8")).toBe("the first archive");
+	});
+
+	test("a crash between the sidecar and the database rename rejoins the pair on the next boot", () => {
+		const live = join(dir, METRICS_DB);
+		writeInheritedCorpus(live);
+		// As if the previous boot moved the sidecar and died before moving the database.
+		writeFileSync(join(dir, `${RETIRED_METRICS_DB}-wal`), "moved already");
+
+		expect(retireInheritedCorpus(dir)).toBe(join(dir, RETIRED_METRICS_DB));
+		expect(readFileSync(join(dir, `${RETIRED_METRICS_DB}-wal`), "utf8")).toBe("moved already");
+	});
+});

package/src/server/requestLog/requestMetrics.ts

@@ -0,0 +1,203 @@
+/**
+ * `cursedbelt-server/request-log` — the request log, "is this app healthy": one row per request
+ * served, in `<APP_DATA_DIR>/metrics.sqlite`, the file station's Metrics page reads for every app on
+ * this Mac (`apps/station/src/server/fleetMetrics.ts`, `METRICS_DB`).
+ *
+ * ── Why it is here (4.21.0) ─────────────────────────────────────────────────
+ * `apps/family` and `apps/roms` held this module byte-identically (task 265's rollout), and
+ * `check-copies` counted it as five copy groups. The API, the header marker and the migration name
+ * are exactly the apps' — a live corpus is recognised by `METRICS_APPLICATION_ID` and by the
+ * `0001_request_metrics` row in its migrations table, so changing either would make every
+ * existing `metrics.sqlite` look inherited and archive it. Bun-only (`bun:sqlite`, `node:fs`): under
+ * Node the export map routes this subpath to `_bunOnly.js`, the way `./engagement` does; it is NOT
+ * part of `./telemetry`, which is Worker-safe (`telemetryIsWorkerSafe.spec.ts`).
+ *
+ * ── Why it came back, 2026-09-23 (task 265) ─────────────────────────────────
+ * `serve.ts` once recorded that request metrics were GONE, on the grounds that the
+ * console that read them was in the retired generation. Station reads them now, and
+ * a measurement found that all eight apps recorded nothing while their
+ * `metrics.sqlite` files — the RETIRED instances' history, inherited at graduation —
+ * rendered as a corpus that had simply gone quiet. This mounts `cursedbelt-server`'s
+ * own seam (`requestLogger` through `createTelemetrySink`, the modules the Worker-safe
+ * `cursedbelt-server/telemetry` leaf re-exports).
+ *
+ * ── 🔴 The inherited file is ARCHIVED, never written ────────────────────────
+ * The file already at `metrics.sqlite` on the live machine is a previous
+ * generation's history under a different schema (`id INTEGER AUTOINCREMENT` plus
+ * `ip`/`country`/`city`/`device`/`form`; this writer inserts `id TEXT` plus
+ * `user_id`). Appending to it would make every future measurement unreadable, so
+ * {@link retireInheritedCorpus} runs at every boot, BEFORE the database is opened:
+ *
+ *   - a file that carries {@link METRICS_APPLICATION_ID} in its header is this
+ *     writer's own, and is left alone — so a second boot is a no-op;
+ *   - anything else is RENAMED, with its `-wal`/`-shm` sidecars, to
+ *     `metrics.retired.sqlite` — or `metrics.retired-2.sqlite`, `-3`, … when that
+ *     name is taken, so two inherited corpora are both kept and nothing is ever
+ *     overwritten. A rename touches no byte of the file, which is the point.
+ *
+ * The marker lives in the SQLite header (`PRAGMA application_id`, offset 68) so it
+ * can be read without opening the database — opening an inherited WAL database
+ * read-write would checkpoint into it on close, which IS writing into it. The
+ * migration checkpoints after stamping it, so the marker is on disk before the
+ * first request is recorded and a crash cannot leave a fresh corpus that the next
+ * boot mistakes for an inherited one.
+ *
+ * ── 🔴 No user id, ever ─────────────────────────────────────────────────────
+ * `cursedbelt-server/engagement`'s header states the split: `metrics/` promises it
+ * holds NO user id, in every app; `engagement.sqlite` is the user-keyed store. The
+ * writer's schema has a `user_id` column and `requestLogger` fills it from
+ * `c.get("userId")`, so the sink here nulls it on every event — whatever any future
+ * middleware puts on the context — and the logger is given no database of its own,
+ * which means it writes no `event_logs` rows either (those carry a `user_id` too,
+ * and nothing in this generation reads them).
+ *
+ * ── Never takes the app down ────────────────────────────────────────────────
+ * {@link openRequestMetricsFromEnv} catches everything and says so on stderr: an
+ * app that cannot record its traffic must still SERVE it. What catches an app that
+ * silently STOPS recording is `requestMetrics.test.ts`, which drives `/healthz`
+ * through a real server and fails when no row lands — `requestMetrics.spec.ts` here, and each
+ * app's own test through its own `createServer`.
+ */
+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 type { MiddlewareHandler } from "hono";
+import { createTelemetrySink, type TelemetrySink } from "../metrics/telemetrySink.js";
+import { requestLogger } from "../middleware/requestLogger.js";
+import { runMigrations } from "../migration/runner.js";
+import { isTestRuntime } from "../satellite/door.js";
+
+/** The file station reads, inside the app's data directory. */
+export const METRICS_DB = "metrics.sqlite";
+/** Where an inherited corpus is moved to — the first free of this and `metrics.retired-<n>.sqlite`. */
+export const RETIRED_METRICS_DB = "metrics.retired.sqlite";
+/** `PRAGMA application_id` of a corpus THIS writer created: "CFRM", cursedforge request metrics. */
+const METRICS_APPLICATION_ID = 0x4346524d;
+
+const SIDECARS = ["-wal", "-shm", "-journal"] as const;
+
+/** `{ name, up(db) }` — the runner's own element type; the package exports the runner, not the type. */
+type Migration = Parameters<typeof runMigrations>[1][number];
+
+/**
+ * The writer's own schema — the columns `cursedbelt-server`'s `metricsBuffer`
+ * inserts, and the ones station's reader asks for (`ts`, `method`, `route`,
+ * `status`, `duration_ms`, `bytes_out`). Append-only: a migration, once applied,
+ * never changes.
+ */
+const REQUEST_METRICS_MIGRATIONS: readonly Migration[] = [
+	{
+		name: "0001_request_metrics",
+		up(db) {
+			db.run(`PRAGMA application_id = ${METRICS_APPLICATION_ID}`);
+			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)`);
+			db.run("CREATE INDEX idx_request_metrics_ts ON request_metrics (ts)");
+		},
+	},
+];
+
+/** The `application_id` stamped in a SQLite file's header, or null when it has no header yet. */
+function headerApplicationId(path: string): number | null {
+	const fd = openSync(path, "r");
+	try {
+		const header = Buffer.alloc(72);
+		if (readSync(fd, header, 0, 72, 0) < 72) return null;
+		return header.readUInt32BE(68);
+	} finally {
+		closeSync(fd);
+	}
+}
+
+const sizeOf = (path: string): number => (existsSync(path) ? statSync(path).size : 0);
+
+/**
+ * Move an inherited `metrics.sqlite` out of the way, or do nothing. Returns the
+ * path it was archived to, or null when there was nothing to archive. See the
+ * header: never writes a byte of the file, never overwrites anything, idempotent.
+ */
+export function retireInheritedCorpus(dir: string): string | null {
+	const live = join(dir, METRICS_DB);
+	if (!existsSync(live)) return null;
+	// An empty file with no journal holds nothing — SQLite simply initialises it.
+	if (sizeOf(live) === 0 && SIDECARS.every((s) => sizeOf(live + s) === 0)) return null;
+	if (headerApplicationId(live) === METRICS_APPLICATION_ID) return null;
+
+	const present = SIDECARS.filter((s) => existsSync(live + s));
+	let target = join(dir, RETIRED_METRICS_DB);
+	for (let n = 2; existsSync(target) || present.some((s) => existsSync(target + s)); n++) {
+		target = join(dir, RETIRED_METRICS_DB.replace(/\.sqlite$/, `-${n}.sqlite`));
+	}
+	// Sidecars FIRST, then the database: a crash between the two leaves the database
+	// where the next boot finds it again, and — because a moved sidecar is no longer
+	// at the source — the loop above picks this same `target`, so the pair is rejoined.
+	for (const s of present) renameSync(live + s, target + s);
+	renameSync(live, target);
+	return target;
+}
+
+/** Retire any inherited corpus, then open (creating if need be) this writer's own. */
+function openMetricsDb(dir: string): { db: Database; archived: string | null } {
+	mkdirSync(dir, { recursive: true });
+	const archived = retireInheritedCorpus(dir);
+	const db = new Database(join(dir, METRICS_DB), { create: true });
+	applyCcPragmas(db);
+	if (runMigrations(db, REQUEST_METRICS_MIGRATIONS).length > 0) {
+		// Put the header marker in the main file now, not at some later checkpoint.
+		db.run("PRAGMA wal_checkpoint(TRUNCATE)");
+	}
+	return { db, archived };
+}
+
+export interface RequestMetrics {
+	db: Database;
+	/** Pending rows are flushed on a 1.5 s timer; `flush()` forces it (tests, shutdown). */
+	sink: TelemetrySink;
+	/** Register FIRST — ahead of every route it must see. */
+	middleware: MiddlewareHandler;
+	/** Where an inherited corpus went at this boot, if one was found. */
+	archived: string | null;
+}
+
+/** Open the corpus in `dir` and build the logger that writes into it. */
+export function openRequestMetrics(dir: string): 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.
+	const sink: TelemetrySink = {
+		record: (event) => inner.record({ ...event, userId: null }),
+		flush: () => inner.flush(),
+		stop: () => inner.stop(),
+		get size() {
+			return inner.size;
+		},
+	};
+	// `null` database: the logger writes through `sink` only, and no `event_logs`.
+	const middleware = requestLogger(null, { sink }) as unknown as MiddlewareHandler;
+	return { db, sink, middleware, archived };
+}
+
+/**
+ * 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 function openRequestMetricsFromEnv(name: string, env: NodeJS.ProcessEnv): RequestMetrics | null {
+	const dir = env.APP_DATA_DIR?.trim();
+	if (!dir || isTestRuntime(env)) return null;
+	try {
+		const metrics = openRequestMetrics(dir);
+		if (metrics.archived) {
+			console.log(`[${name}] request metrics: archived the inherited corpus to ${metrics.archived}`);
+		}
+		return metrics;
+	} catch (error) {
+		console.error(
+			`[${name}] request metrics disabled: ${error instanceof Error ? error.message : String(error)}`,
+		);
+		return null;
+	}
+}

package/src/server/ws/hub.spec.ts

@@ -109,6 +109,34 @@ describe('createWsHub — message routing & lifecycle', () => {
   });
 });
 
+describe('🔴 onDisconnect sees the hub WITHOUT the client that left', () => {
+  test('a presence roster read inside onDisconnect no longer lists the leaver', () => {
+    const rosters: string[][] = [];
+    let stillRegistered: boolean | undefined;
+    const hub = createWsHub({
+      channels: {
+        test: {
+          name: 'test',
+          presence: true,
+          onMessage: () => {},
+          onDisconnect: (client, h) => {
+            stillRegistered = h.getClient(client.id) !== undefined;
+            rosters.push(h.getPresence('test').map((row) => row.userId));
+          },
+        },
+      },
+      authenticate: async () => testUser,
+    });
+    connect(hub, data({ clientId: 'stays', user: { ...testUser, id: 'u-stays' } }));
+    const leaver = connect(hub, data({ clientId: 'leaves', user: { ...testUser, id: 'u-leaves' } }));
+    hub.handlers.close?.(leaver, 1000, 'bye');
+    // Before 4.20.1 this was ['u-stays', 'u-leaves'] — the stale roster the recipe broadcast.
+    expect(rosters).toEqual([['u-stays']]);
+    expect(stillRegistered).toBe(false);
+    hub.close();
+  });
+});
+
 describe('createWsHub — broadcast / send / room', () => {
   const hubWith = () =>
     createWsHub({

package/src/server/ws/hub.ts

@@ -130,8 +130,13 @@ export function createWsHub<T extends Record<string, WsChannel<any>>>(opts: WsHu
       close(ws) {
         const client = clientFromWs(ws);
         if (!client) return;
-        channelOf(client.channel)?.onDisconnect?.(client, hub);
+        // 🔴 Remove FIRST, then tell the channel. The recipe every presence app follows is
+        // "broadcast hub.getPresence(channel) from onDisconnect" (cursedbelt's usePresence doc),
+        // and until 4.20.1 this called onDisconnect while the leaver was still registered — so
+        // the roster it broadcast still listed the person who had just left. apps/roms deferred a
+        // microtask to work around it (src/server/presence.ts). hub.spec.ts pins the order.
         clients.delete(client.id);
+        channelOf(client.channel)?.onDisconnect?.(client, hub);
       },
     },
     broadcast(channel, event, data) {

package/src/server/ws/types.ts

@@ -67,7 +67,8 @@ export interface WsChannel<TMsg = WsMessage> {
   onConnect?(client: WsClient, hub: WsHub): void;
   /** Fired once per inbound frame (the parsed `{ event, data }` envelope). */
   onMessage(client: WsClient, msg: TMsg, hub: WsHub): void;
-  /** Fired when the socket closes (explicit, stale-culled, or peer-dropped). */
+  /** Fired when the socket closes (explicit, stale-culled, or peer-dropped) — AFTER the client is
+   *  removed, so `hub.getPresence()` here is the roster without it (4.20.1). */
   onDisconnect?(client: WsClient, hub: WsHub): void;
   /** Whether this channel contributes to {@link WsHub.getPresence}. Default: false. */
   presence?: boolean;

package/src/subpathReach.ts

@@ -57,5 +57,7 @@ export const MAY_NEED_BUN: Record<string, readonly string[]> = {
 	// The engagement store IS `engagement.sqlite` on the Mac (4.19.0, task 280) — the recorder
 	// runs where the app's own database is. A Worker app records nothing until it has a D1 store.
 	'./engagement': ['bun:sqlite'],
+	// The request log IS `metrics.sqlite` beside the app's data (4.21.0) — a Mac-hosted server's.
+	'./request-log': ['bun:sqlite'],
 };