cursedbelt-server 4.26.1 → 4.27.0

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

@@ -0,0 +1,67 @@
+/**
+ * `cursedbelt-server/engagement/d1` — the engagement recorder over D1, for an app a Worker serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `./engagement` is Bun-only: its store is a synchronous `bun:sqlite` file (`engagement.sqlite`)
+ * that station's Metrics page reads off disk. A Worker has neither, so an app that moved to one
+ * stopped being heard with no error anywhere — `collections` from its 2026-09-22 cutover until
+ * this subpath (task 2096). The SAME three tables live in the app's own D1 instead (its
+ * `db/schema.sql`, from {@link ENGAGEMENT_DDL}), written with the SAME fold (`./policy.ts` →
+ * `foldView`, `dayKey`, `resolvePlace`), and station reads them from D1 for any Worker-served app.
+ *
+ * It was `apps/music/src/server/engagementD1.ts` plus a copied `kit/engagement/policy.ts` held
+ * byte-identical by a parity test (task 2081). collections was the second consumer, so it was
+ * lifted here rather than copied again — and the policy copy went with it: this module imports
+ * the library's own `policy.ts`, so there is one privacy rule, not one per Worker.
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./store.js` or `./api.js` here.
+ *
+ * 🔴 The kit's privacy story holds unchanged: the place is resolved against the app's own route
+ * manifest AT THE DOOR, so an id, an album name or a search string never reaches a row; the
+ * account is the session's subject, never anything in the body. Mount it INSIDE the session gate.
+ *
+ * 🔴 {@link ENGAGEMENT_DDL} must stay byte-identical in effect to `EngagementStore`'s `migrate()` —
+ * station reads both shapes with one query set. `d1.spec.ts` builds both and compares their
+ * `sqlite_master` rows, so a column added to one and not the other is a red.
+ *
+ * ```ts
+ * import { createD1EngagementRecorder, placesFromManifest } from "cursedbelt-server/engagement/d1";
+ * import routesManifest from "../routes.manifest.json";
+ *
+ * gated.route("/api/engagement", createD1EngagementRecorder({
+ *   db, places: placesFromManifest(routesManifest), resolveUser: (c) => sso.userOf(c)?.id ?? null,
+ * }));
+ * ```
+ */
+import type { D1LikeDatabase } from "../d1/types.js";
+import type { Context } from "hono";
+import { Hono } from "hono";
+import { type PlaceRef } from "./policy.js";
+/** The kit store's own tables and indexes, as one-line DDL — see the header. */
+export declare const ENGAGEMENT_DDL: readonly string[];
+/**
+ * Record one view — the kit's `EngagementStore.recordView`, asynchronously: one read (the
+ * account's previous view) and ONE batch of up to five statements, so a view is atomic and
+ * costs two D1 round trips however much it credits.
+ */
+export declare function recordViewD1(db: D1LikeDatabase, input: {
+    userKey: string;
+    place: string;
+    ts: number;
+}): Promise<{
+    newSession: boolean;
+    activeMs: number;
+}>;
+/**
+ * The recorder as the kit's `createEngagementRecorder` mounts it — `POST /view` under
+ * `ENGAGEMENT_BASE_PATH` — over D1. Recording only: there is no read surface here, as there is
+ * none on the Mac; station reads the tables directly.
+ */
+export declare function createD1EngagementRecorder(options: {
+    db: D1LikeDatabase;
+    places: readonly PlaceRef[];
+    resolveUser: (c: Context) => string | null;
+    now?: () => number;
+}): Hono;
+export { placesFromManifest } from "./manifestPlaces.js";

package/dist/server/engagement/d1.js

@@ -0,0 +1,81 @@
+import { Hono } from "hono";
+import { dayKey, foldView, OTHER_PLACE, resolvePlace } from "./policy.js";
+/** The kit store's own tables and indexes, as one-line DDL — see the header. */
+export const ENGAGEMENT_DDL = [
+    "CREATE TABLE IF NOT EXISTS engagement_days ( user_key TEXT NOT NULL, place TEXT NOT NULL, day TEXT NOT NULL, views INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, PRIMARY KEY (user_key, place, day) )",
+    "CREATE INDEX IF NOT EXISTS idx_engagement_days_day ON engagement_days (day)",
+    "CREATE TABLE IF NOT EXISTS engagement_places ( user_key TEXT NOT NULL, place TEXT NOT NULL, views INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, PRIMARY KEY (user_key, place) )",
+    "CREATE INDEX IF NOT EXISTS idx_engagement_places_last ON engagement_places (last_ts)",
+    "CREATE TABLE IF NOT EXISTS engagement_users ( user_key TEXT PRIMARY KEY, views INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, last_place TEXT NOT NULL DEFAULT '' )",
+];
+/**
+ * Record one view — the kit's `EngagementStore.recordView`, asynchronously: one read (the
+ * account's previous view) and ONE batch of up to five statements, so a view is atomic and
+ * costs two D1 round trips however much it credits.
+ */
+export async function recordViewD1(db, input) {
+    const { userKey, place, ts } = input;
+    const prior = await db
+        .prepare("SELECT last_ts, last_place FROM engagement_users WHERE user_key = ?")
+        .bind(userKey)
+        .first();
+    const fold = foldView(prior ? prior.last_ts : null, ts);
+    const sessionDelta = fold.newSession ? 1 : 0;
+    const statements = [];
+    if (fold.activeMs > 0 && prior?.last_place) {
+        // The time since the last view is credited to the place the account was LOOKING AT.
+        statements.push(db
+            .prepare("UPDATE engagement_days SET active_ms = active_ms + ? WHERE user_key = ? AND place = ? AND day = ?")
+            .bind(fold.activeMs, userKey, prior.last_place, dayKey(prior.last_ts)), db
+            .prepare("UPDATE engagement_places SET active_ms = active_ms + ? WHERE user_key = ? AND place = ?")
+            .bind(fold.activeMs, userKey, prior.last_place));
+    }
+    statements.push(db
+        .prepare(`INSERT INTO engagement_days (user_key, place, day, views, active_ms, sessions, first_ts, last_ts)
+				 VALUES (?, ?, ?, 1, 0, ?, ?, ?)
+				 ON CONFLICT(user_key, place, day) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, last_ts = excluded.last_ts`)
+        .bind(userKey, place, dayKey(ts), sessionDelta, ts, ts), db
+        .prepare(`INSERT INTO engagement_places (user_key, place, views, sessions, active_ms, first_ts, last_ts)
+				 VALUES (?, ?, 1, ?, 0, ?, ?)
+				 ON CONFLICT(user_key, place) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, last_ts = excluded.last_ts`)
+        .bind(userKey, place, sessionDelta, ts, ts), db
+        .prepare(`INSERT INTO engagement_users (user_key, views, sessions, active_ms, first_ts, last_ts, last_place)
+				 VALUES (?, 1, ?, 0, ?, ?, ?)
+				 ON CONFLICT(user_key) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, active_ms = active_ms + ?,
+				   last_ts = excluded.last_ts, last_place = excluded.last_place`)
+        .bind(userKey, sessionDelta, ts, ts, place, fold.activeMs));
+    await db.batch(statements);
+    return fold;
+}
+/**
+ * The recorder as the kit's `createEngagementRecorder` mounts it — `POST /view` under
+ * `ENGAGEMENT_BASE_PATH` — over D1. Recording only: there is no read surface here, as there is
+ * none on the Mac; station reads the tables directly.
+ */
+export function createD1EngagementRecorder(options) {
+    const app = new Hono();
+    const now = options.now ?? (() => Date.now());
+    app.post("/view", async (c) => {
+        const userKey = options.resolveUser(c);
+        if (!userKey)
+            return c.json({ error: "unauthenticated" }, 401);
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: "expected a json body" }, 400);
+        }
+        const claimed = body?.place;
+        if (typeof claimed !== "string")
+            return c.json({ error: "place must be a string" }, 400);
+        const place = resolvePlace(claimed, options.places);
+        const fold = await recordViewD1(options.db, { userKey, place, ts: now() });
+        return c.json({ ok: true, place, bucketed: place === OTHER_PLACE, ...fold });
+    });
+    return app;
+}
+export { placesFromManifest } from "./manifestPlaces.js";

package/dist/server/engagement/manifestPlaces.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A parsed `routes.manifest.json` → the place allowlist. Pure, and Worker-safe: `places.ts`
+ * reads the file off disk for a Bun server, and a Worker hands over the JSON it bundles
+ * (`./d1.ts`). ONE rule for both — until task 2096 music's Worker carried its own copy of it.
+ *
+ * Anything it cannot read is `[]`, never a throw: see `places.ts`, "Missing is EMPTY".
+ */
+import type { PlaceRef } from "./policy.js";
+export declare function placesFromManifest(doc: unknown): PlaceRef[];

package/dist/server/engagement/manifestPlaces.js

@@ -0,0 +1,17 @@
+export function placesFromManifest(doc) {
+    const routes = Array.isArray(doc) ? doc : doc?.routes;
+    if (!Array.isArray(routes))
+        return [];
+    const seen = new Set();
+    const places = [];
+    for (const raw of routes) {
+        const r = raw;
+        if (!r || typeof r.id !== "string" || !r.id || seen.has(r.id))
+            continue;
+        seen.add(r.id);
+        places.push({ id: r.id, path: typeof r.path === "string" ? r.path : "" });
+    }
+    // Sorted so the allowlist a board renders is stable between deployments.
+    places.sort((a, b) => a.id.localeCompare(b.id));
+    return places;
+}

package/dist/server/engagement/places.js

@@ -24,6 +24,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { placesFromManifest } from "./manifestPlaces.js";
 /** Where the manifest sits, in a source tree and in a built artifact alike. */
 const MANIFEST = "routes.manifest.json";
 /**
@@ -38,24 +39,7 @@ export function engagementPlacesFor(dir) {
     if (!existsSync(path))
         return [];
     try {
-        const doc = JSON.parse(readFileSync(path, "utf8"));
-        const routes = Array.isArray(doc)
-            ? doc
-            : doc.routes;
-        if (!Array.isArray(routes))
-            return [];
-        const seen = new Set();
-        const places = [];
-        for (const raw of routes) {
-            const r = raw;
-            if (typeof r.id !== "string" || !r.id || seen.has(r.id))
-                continue;
-            seen.add(r.id);
-            places.push({ id: r.id, path: typeof r.path === "string" ? r.path : "" });
-        }
-        // Sorted so the allowlist a board renders is stable between deployments.
-        places.sort((a, b) => a.id.localeCompare(b.id));
-        return places;
+        return placesFromManifest(JSON.parse(readFileSync(path, "utf8")));
     }
     catch {
         return [];

package/docs/engagement.md

@@ -44,4 +44,10 @@ manifest parses (`apps/roms/routes.manifest.test.ts` is the pattern).
 excluded app, `SATELLITE_ENGAGEMENT=0` or an unresolvable data directory each turn recording OFF
 and say why, and the app still boots.
 
+**On a Worker**, the same three tables live in the app's own D1 instead:
+`cursedbelt-server/engagement/d1` (since 4.27.0, task 2096) exports `ENGAGEMENT_DDL` for the
+app's `db/schema.sql`, `createD1EngagementRecorder` to mount inside the gate, and
+`placesFromManifest` for the bundled `routes.manifest.json`. It is Worker-safe and uses the same
+`policy.ts`, so there is one privacy rule whichever host records. station reads either shape.
+
 Cite this page from an app as `cursedbelt-server/docs/engagement.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.26.1",
+	"version": "4.27.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.",
@@ -125,6 +125,12 @@
 			"source": "./src/server/engagement/index.ts",
 			"import": "./dist/server/_bunOnly.js"
 		},
+		"./engagement/d1": {
+			"types": "./dist/server/engagement/d1.d.ts",
+			"bun": "./src/server/engagement/d1.ts",
+			"source": "./src/server/engagement/d1.ts",
+			"import": "./dist/server/engagement/d1.js"
+		},
 		"./errors": {
 			"types": "./dist/server/errors.d.ts",
 			"bun": "./src/server/errors.ts",

package/src/server/engagement/d1.spec.ts

@@ -0,0 +1,102 @@
+/**
+ * The Worker's engagement recorder is the kit's, over D1 — the SAME tables and the SAME rows for
+ * the same views, because station reads both with one query set (tasks 2081, 2096).
+ */
+import { Database } from 'bun:sqlite';
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Hono } from 'hono';
+import { createLocalD1 } from '../d1/local.js';
+import { createD1EngagementRecorder, ENGAGEMENT_DDL, placesFromManifest, recordViewD1 } from './d1.js';
+import { engagementPlacesFor } from './places.js';
+import { EngagementStore } from './store.js';
+
+const dirs: string[] = [];
+afterEach(() => {
+	for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true });
+});
+const tempDir = (): string => {
+	const dir = mkdtempSync(join(tmpdir(), 'engagement-d1-'));
+	dirs.push(dir);
+	return dir;
+};
+const kitStore = (): EngagementStore => new EngagementStore({ dbPath: join(tempDir(), 'engagement.sqlite') });
+const d1 = () => {
+	const sqlite = new Database(':memory:');
+	for (const ddl of ENGAGEMENT_DDL) sqlite.run(ddl);
+	return { sqlite, db: createLocalD1(sqlite) };
+};
+const shape = (db: Database) =>
+	(
+		db
+			.query("SELECT type, name, sql FROM sqlite_master WHERE name LIKE '%engagement%' AND sql IS NOT NULL ORDER BY name")
+			.all() as { type: string; name: string; sql: string }[]
+	).map((r) => ({ type: r.type, name: r.name, sql: r.sql.replace(/\s+/g, ' ').replace('IF NOT EXISTS ', '').trim() }));
+const dump = (db: Database) => ({
+	days: db.query('SELECT * FROM engagement_days ORDER BY user_key, place, day').all(),
+	places: db.query('SELECT * FROM engagement_places ORDER BY user_key, place').all(),
+	users: db.query('SELECT * FROM engagement_users ORDER BY user_key').all(),
+});
+
+describe('cursedbelt-server/engagement/d1', () => {
+	test("🔴 creates exactly the kit store's tables and indexes — station reads both with one query set", () => {
+		const kit = kitStore();
+		const { sqlite } = d1();
+		expect(shape(sqlite)).toEqual(shape(kit.handle));
+	});
+
+	test("🔴 the same views produce the same rows as the kit's store — sessions, dwell, days", async () => {
+		const kit = kitStore();
+		const { sqlite, db } = d1();
+		const t0 = Date.UTC(2026, 8, 23, 10, 0, 0);
+		const views = [
+			{ userKey: 'u1', place: 'library', ts: t0 },
+			{ userKey: 'u1', place: 'downloads', ts: t0 + 40_000 },
+			{ userKey: 'u2', place: 'library', ts: t0 + 50_000 },
+			{ userKey: 'u1', place: 'library', ts: t0 + 90_000 },
+			// A new session (a long gap) on the next day.
+			{ userKey: 'u1', place: 'library', ts: t0 + 26 * 3_600_000 },
+		];
+		for (const v of views) expect(await recordViewD1(db, v)).toEqual(kit.recordView(v));
+		expect(dump(sqlite)).toEqual(dump(kit.handle));
+	});
+
+	test('records only a signed-in account, and buckets an off-manifest place as `other`', async () => {
+		const { sqlite, db } = d1();
+		const places = placesFromManifest({ routes: [{ id: 'library', path: '/library' }, { id: 'library' }, { path: '/x' }] });
+		expect(places).toEqual([{ id: 'library', path: '/library' }]);
+		let user: string | null = null;
+		const app = new Hono().route('/api/engagement', createD1EngagementRecorder({ db, places, resolveUser: () => user }));
+		const post = (place: unknown) =>
+			app.request('http://x/api/engagement/view', {
+				method: 'POST',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({ place }),
+			});
+		expect((await post('library')).status).toBe(401);
+		user = 'u1';
+		expect(await (await post('library')).json()).toMatchObject({ ok: true, place: 'library', bucketed: false });
+		// An id, an album name, a search string — never a row of its own.
+		expect(await (await post('album:Some Private Name')).json()).toMatchObject({ place: 'other', bucketed: true });
+		expect((await post(42)).status).toBe(400);
+		expect(sqlite.query('SELECT place FROM engagement_places ORDER BY place').all()).toEqual([
+			{ place: 'library' },
+			{ place: 'other' },
+		]);
+	});
+
+	test('🔴 ONE manifest rule: a Worker handed the JSON and a Bun server reading the file agree', async () => {
+		const doc = { routes: [{ id: 'queue', path: '/#/queue' }, { id: 'home', path: '/' }, { id: 'queue' }, { id: '' }, null] };
+		const dir = tempDir();
+		await Bun.write(join(dir, 'routes.manifest.json'), JSON.stringify(doc));
+		expect(placesFromManifest(doc)).toEqual([
+			{ id: 'home', path: '/' },
+			{ id: 'queue', path: '/#/queue' },
+		]);
+		expect(engagementPlacesFor(dir)).toEqual(placesFromManifest(doc));
+		expect(placesFromManifest('not a manifest')).toEqual([]);
+		expect(placesFromManifest(null)).toEqual([]);
+	});
+});

package/src/server/engagement/d1.ts

@@ -0,0 +1,141 @@
+/**
+ * `cursedbelt-server/engagement/d1` — the engagement recorder over D1, for an app a Worker serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `./engagement` is Bun-only: its store is a synchronous `bun:sqlite` file (`engagement.sqlite`)
+ * that station's Metrics page reads off disk. A Worker has neither, so an app that moved to one
+ * stopped being heard with no error anywhere — `collections` from its 2026-09-22 cutover until
+ * this subpath (task 2096). The SAME three tables live in the app's own D1 instead (its
+ * `db/schema.sql`, from {@link ENGAGEMENT_DDL}), written with the SAME fold (`./policy.ts` →
+ * `foldView`, `dayKey`, `resolvePlace`), and station reads them from D1 for any Worker-served app.
+ *
+ * It was `apps/music/src/server/engagementD1.ts` plus a copied `kit/engagement/policy.ts` held
+ * byte-identical by a parity test (task 2081). collections was the second consumer, so it was
+ * lifted here rather than copied again — and the policy copy went with it: this module imports
+ * the library's own `policy.ts`, so there is one privacy rule, not one per Worker.
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./store.js` or `./api.js` here.
+ *
+ * 🔴 The kit's privacy story holds unchanged: the place is resolved against the app's own route
+ * manifest AT THE DOOR, so an id, an album name or a search string never reaches a row; the
+ * account is the session's subject, never anything in the body. Mount it INSIDE the session gate.
+ *
+ * 🔴 {@link ENGAGEMENT_DDL} must stay byte-identical in effect to `EngagementStore`'s `migrate()` —
+ * station reads both shapes with one query set. `d1.spec.ts` builds both and compares their
+ * `sqlite_master` rows, so a column added to one and not the other is a red.
+ *
+ * ```ts
+ * import { createD1EngagementRecorder, placesFromManifest } from "cursedbelt-server/engagement/d1";
+ * import routesManifest from "../routes.manifest.json";
+ *
+ * gated.route("/api/engagement", createD1EngagementRecorder({
+ *   db, places: placesFromManifest(routesManifest), resolveUser: (c) => sso.userOf(c)?.id ?? null,
+ * }));
+ * ```
+ */
+import type { D1LikeDatabase } from "../d1/types.js";
+import type { Context } from "hono";
+import { Hono } from "hono";
+import { dayKey, foldView, OTHER_PLACE, type PlaceRef, resolvePlace } from "./policy.js";
+
+/** The kit store's own tables and indexes, as one-line DDL — see the header. */
+export const ENGAGEMENT_DDL: readonly string[] = [
+	"CREATE TABLE IF NOT EXISTS engagement_days ( user_key TEXT NOT NULL, place TEXT NOT NULL, day TEXT NOT NULL, views INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, PRIMARY KEY (user_key, place, day) )",
+	"CREATE INDEX IF NOT EXISTS idx_engagement_days_day ON engagement_days (day)",
+	"CREATE TABLE IF NOT EXISTS engagement_places ( user_key TEXT NOT NULL, place TEXT NOT NULL, views INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, PRIMARY KEY (user_key, place) )",
+	"CREATE INDEX IF NOT EXISTS idx_engagement_places_last ON engagement_places (last_ts)",
+	"CREATE TABLE IF NOT EXISTS engagement_users ( user_key TEXT PRIMARY KEY, views INTEGER NOT NULL DEFAULT 0, sessions INTEGER NOT NULL DEFAULT 0, active_ms INTEGER NOT NULL DEFAULT 0, first_ts INTEGER NOT NULL, last_ts INTEGER NOT NULL, last_place TEXT NOT NULL DEFAULT '' )",
+];
+
+/**
+ * Record one view — the kit's `EngagementStore.recordView`, asynchronously: one read (the
+ * account's previous view) and ONE batch of up to five statements, so a view is atomic and
+ * costs two D1 round trips however much it credits.
+ */
+export async function recordViewD1(
+	db: D1LikeDatabase,
+	input: { userKey: string; place: string; ts: number },
+): Promise<{ newSession: boolean; activeMs: number }> {
+	const { userKey, place, ts } = input;
+	const prior = await db
+		.prepare("SELECT last_ts, last_place FROM engagement_users WHERE user_key = ?")
+		.bind(userKey)
+		.first<{ last_ts: number; last_place: string }>();
+	const fold = foldView(prior ? prior.last_ts : null, ts);
+	const sessionDelta = fold.newSession ? 1 : 0;
+	const statements = [];
+	if (fold.activeMs > 0 && prior?.last_place) {
+		// The time since the last view is credited to the place the account was LOOKING AT.
+		statements.push(
+			db
+				.prepare("UPDATE engagement_days SET active_ms = active_ms + ? WHERE user_key = ? AND place = ? AND day = ?")
+				.bind(fold.activeMs, userKey, prior.last_place, dayKey(prior.last_ts)),
+			db
+				.prepare("UPDATE engagement_places SET active_ms = active_ms + ? WHERE user_key = ? AND place = ?")
+				.bind(fold.activeMs, userKey, prior.last_place),
+		);
+	}
+	statements.push(
+		db
+			.prepare(
+				`INSERT INTO engagement_days (user_key, place, day, views, active_ms, sessions, first_ts, last_ts)
+				 VALUES (?, ?, ?, 1, 0, ?, ?, ?)
+				 ON CONFLICT(user_key, place, day) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, last_ts = excluded.last_ts`,
+			)
+			.bind(userKey, place, dayKey(ts), sessionDelta, ts, ts),
+		db
+			.prepare(
+				`INSERT INTO engagement_places (user_key, place, views, sessions, active_ms, first_ts, last_ts)
+				 VALUES (?, ?, 1, ?, 0, ?, ?)
+				 ON CONFLICT(user_key, place) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, last_ts = excluded.last_ts`,
+			)
+			.bind(userKey, place, sessionDelta, ts, ts),
+		db
+			.prepare(
+				`INSERT INTO engagement_users (user_key, views, sessions, active_ms, first_ts, last_ts, last_place)
+				 VALUES (?, 1, ?, 0, ?, ?, ?)
+				 ON CONFLICT(user_key) DO UPDATE SET
+				   views = views + 1, sessions = sessions + excluded.sessions, active_ms = active_ms + ?,
+				   last_ts = excluded.last_ts, last_place = excluded.last_place`,
+			)
+			.bind(userKey, sessionDelta, ts, ts, place, fold.activeMs),
+	);
+	await db.batch(statements);
+	return fold;
+}
+
+/**
+ * The recorder as the kit's `createEngagementRecorder` mounts it — `POST /view` under
+ * `ENGAGEMENT_BASE_PATH` — over D1. Recording only: there is no read surface here, as there is
+ * none on the Mac; station reads the tables directly.
+ */
+export function createD1EngagementRecorder(options: {
+	db: D1LikeDatabase;
+	places: readonly PlaceRef[];
+	resolveUser: (c: Context) => string | null;
+	now?: () => number;
+}): Hono {
+	const app = new Hono();
+	const now = options.now ?? (() => Date.now());
+	app.post("/view", async (c) => {
+		const userKey = options.resolveUser(c);
+		if (!userKey) return c.json({ error: "unauthenticated" }, 401);
+		let body: unknown;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({ error: "expected a json body" }, 400);
+		}
+		const claimed = (body as { place?: unknown } | null)?.place;
+		if (typeof claimed !== "string") return c.json({ error: "place must be a string" }, 400);
+		const place = resolvePlace(claimed, options.places);
+		const fold = await recordViewD1(options.db, { userKey, place, ts: now() });
+		return c.json({ ok: true, place, bucketed: place === OTHER_PLACE, ...fold });
+	});
+	return app;
+}
+
+export { placesFromManifest } from "./manifestPlaces.js";

package/src/server/engagement/manifestPlaces.ts

@@ -0,0 +1,24 @@
+/**
+ * A parsed `routes.manifest.json` → the place allowlist. Pure, and Worker-safe: `places.ts`
+ * reads the file off disk for a Bun server, and a Worker hands over the JSON it bundles
+ * (`./d1.ts`). ONE rule for both — until task 2096 music's Worker carried its own copy of it.
+ *
+ * Anything it cannot read is `[]`, never a throw: see `places.ts`, "Missing is EMPTY".
+ */
+import type { PlaceRef } from "./policy.js";
+
+export function placesFromManifest(doc: unknown): PlaceRef[] {
+	const routes = Array.isArray(doc) ? doc : ((doc as { routes?: unknown } | null)?.routes as unknown[] | undefined);
+	if (!Array.isArray(routes)) return [];
+	const seen = new Set<string>();
+	const places: PlaceRef[] = [];
+	for (const raw of routes) {
+		const r = raw as { id?: unknown; path?: unknown } | null;
+		if (!r || typeof r.id !== "string" || !r.id || seen.has(r.id)) continue;
+		seen.add(r.id);
+		places.push({ id: r.id, path: typeof r.path === "string" ? r.path : "" });
+	}
+	// Sorted so the allowlist a board renders is stable between deployments.
+	places.sort((a, b) => a.id.localeCompare(b.id));
+	return places;
+}

package/src/server/engagement/places.ts

@@ -24,6 +24,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { placesFromManifest } from "./manifestPlaces.js";
 
 /** Where the manifest sits, in a source tree and in a built artifact alike. */
 const MANIFEST = "routes.manifest.json";
@@ -54,22 +55,7 @@ export function engagementPlacesFor(dir: string): EngagementPlace[] {
 	const path = join(dir, MANIFEST);
 	if (!existsSync(path)) return [];
 	try {
-		const doc = JSON.parse(readFileSync(path, "utf8")) as unknown;
-		const routes = Array.isArray(doc)
-			? doc
-			: ((doc as { routes?: unknown }).routes as unknown[] | undefined);
-		if (!Array.isArray(routes)) return [];
-		const seen = new Set<string>();
-		const places: EngagementPlace[] = [];
-		for (const raw of routes) {
-			const r = raw as { id?: unknown; path?: unknown };
-			if (typeof r.id !== "string" || !r.id || seen.has(r.id)) continue;
-			seen.add(r.id);
-			places.push({ id: r.id, path: typeof r.path === "string" ? r.path : "" });
-		}
-		// Sorted so the allowlist a board renders is stable between deployments.
-		places.sort((a, b) => a.id.localeCompare(b.id));
-		return places;
+		return placesFromManifest(JSON.parse(readFileSync(path, "utf8")) as unknown);
 	} catch {
 		return [];
 	}

package/src/server/telemetryIsWorkerSafe.spec.ts

@@ -89,3 +89,21 @@ describe('cursedbelt-server/telemetry', () => {
 		expect(found).toEqual(['bun:sqlite']);
 	});
 });
+
+describe('🔴 cursedbelt-server/engagement/d1 — a Worker mounts it (task 2096)', () => {
+	test('reaches no `bun:` module at runtime — not the store, not the Bun-only barrel', () => {
+		const { files, bunImports } = runtimeGraph(join(import.meta.dir, 'engagement', 'd1.ts'));
+		expect(bunImports).toEqual([]);
+		// Not vacuous: the policy and the manifest rule are both in the graph, and the store is not.
+		expect(files.some((f) => f.endsWith('engagement/policy.ts'))).toBe(true);
+		expect(files.some((f) => f.endsWith('engagement/manifestPlaces.ts'))).toBe(true);
+		expect(files.some((f) => f.endsWith('engagement/store.ts'))).toBe(false);
+	});
+
+	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['./engagement/d1']?.import).toBe('./dist/server/engagement/d1.js');
+	});
+});