cursedbelt-server 4.26.1 → 4.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.26.1",
+	"version": "4.28.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.",
@@ -47,6 +47,12 @@
 			"source": "./src/server/activity/index.ts",
 			"import": "./dist/server/activity/index.js"
 		},
+		"./activity/d1": {
+			"types": "./dist/server/activity/d1.d.ts",
+			"bun": "./src/server/activity/d1.ts",
+			"source": "./src/server/activity/d1.ts",
+			"import": "./dist/server/activity/d1.js"
+		},
 		"./context": {
 			"types": "./dist/server/context.d.ts",
 			"bun": "./src/server/context.ts",
@@ -125,6 +131,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",
@@ -240,6 +252,12 @@
 			"source": "./src/server/notifications/index.ts",
 			"import": "./dist/server/notifications/index.js"
 		},
+		"./notifications/d1": {
+			"types": "./dist/server/notifications/d1.d.ts",
+			"bun": "./src/server/notifications/d1.ts",
+			"source": "./src/server/notifications/d1.ts",
+			"import": "./dist/server/notifications/d1.js"
+		},
 		"./resume": {
 			"types": "./dist/server/resume/index.d.ts",
 			"bun": "./src/server/resume/index.ts",
@@ -276,6 +294,12 @@
 			"source": "./src/server/sharing/index.ts",
 			"import": "./dist/server/sharing/index.js"
 		},
+		"./sharing/d1": {
+			"types": "./dist/server/sharing/d1.d.ts",
+			"bun": "./src/server/sharing/d1.ts",
+			"source": "./src/server/sharing/d1.ts",
+			"import": "./dist/server/sharing/d1.js"
+		},
 		"./sqlite": {
 			"types": "./dist/server/sqlite/index.d.ts",
 			"bun": "./src/server/sqlite/index.ts",

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

@@ -0,0 +1,169 @@
+/**
+ * The D1 activity log is the sync log, asynchronously — the same events, pages, counts, facets
+ * and sources for the same calls, over the same table (task 393, `apps/family`).
+ *
+ * The parity scenario drives both logs — each with a share store writing `share_events` into
+ * the same database, merged in through `shareEventsSource` — with one script and one clock, and
+ * compares every result and then the table. It runs over the local driver and over the fake D1
+ * binding, which refuses the binds real D1 refuses.
+ */
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import { createFakeD1Binding } from "../d1/fakeD1.js";
+import { createLocalD1 } from "../d1/local.js";
+import { createRemoteD1 } from "../d1/remote.js";
+import type { D1LikeDatabase } from "../d1/types.js";
+import { runMigrations } from "../migration/runner.js";
+import { createD1ShareStore, SHARE_DDL, user } from "../sharing/d1.js";
+import { createShareStore } from "../sharing/store.js";
+import { ACTIVITY_DDL, type AsyncActivityLog, createD1ActivityLog, shareEventsSource } from "./d1.js";
+import { ACTIVITY_MIGRATIONS } from "./migrations.js";
+import { type ActivityLog, createActivityLog } from "./store.js";
+
+const APP = "family";
+
+/** One minute per call, from a fixed start, identical for both logs. */
+const clock = () => {
+	let at = Date.parse("2026-08-11T00:00:00.000Z");
+	return () => {
+		const value = new Date(at).toISOString();
+		at += 60_000;
+		return value;
+	};
+};
+
+const DRIVERS: Record<string, (sqlite: Database) => D1LikeDatabase> = {
+	local: (sqlite) => createLocalD1(sqlite),
+	"remote (fake D1 binding)": (sqlite) => createRemoteD1(createFakeD1Binding(sqlite)),
+};
+const local = DRIVERS.local as (sqlite: Database) => D1LikeDatabase;
+
+const withDdl = (...ddl: (readonly string[])[]): Database => {
+	const sqlite = new Database(":memory:");
+	for (const statements of ddl) for (const statement of statements) sqlite.run(statement);
+	return sqlite;
+};
+
+type Grant = (email: string) => unknown;
+
+const SCENARIO: ReadonlyArray<(log: ActivityLog | AsyncActivityLog, grant: Grant) => unknown> = [
+	(log) => log.sources(),
+	(log) =>
+		log.record({
+			actor: " Curt@Example.com ",
+			action: "person.create",
+			resource: { kind: "person", id: "a" },
+			note: "100% done",
+			data: { bytes: 4096 },
+		}),
+	(_log, grant) => grant("aunt@example.com"),
+	(log) => log.record({ actor: "other@example.com", action: "person.delete", resource: { kind: "person", id: "b" } }),
+	(log) => log.record({ actor: "curt@example.com", action: "backup.create", outcome: "error", note: "nothing like it" }),
+	(log) => log.record({ actor: "curt@example.com", action: "backup.create", at: "2026-08-10T23:59:00.000Z" }),
+	(_log, grant) => grant("cousin@example.com"),
+	(log) => log.query(),
+	(log) => log.query({ limit: 2 }),
+	(log) => log.query({ limit: 10_000 }),
+	(log) => log.query({ actor: "CURT@example.com" }),
+	(log) => log.query({ action: "person." }),
+	(log) => log.query({ action: "share." }),
+	(log) => log.query({ action: "person.create" }),
+	(log) => log.query({ kind: "person", resourceId: "b" }),
+	(log) => log.query({ outcome: "error" }),
+	(log) => log.query({ since: "2026-08-11T00:02:00.000Z" }),
+	(log) => log.query({ until: "2026-08-11T00:00:30.000Z" }),
+	(log) => log.query({ q: "100%" }),
+	(log) => log.query({ q: "%d" }),
+	(log) => log.query({ source: "share" }),
+	(log) => log.query({ source: "log", limit: 1 }),
+	(log) => log.query({ source: "nothing" }),
+	(log) => log.count(),
+	(log) => log.count({ source: "share" }),
+	(log) => log.facets(),
+	(log) => log.facets({ actor: "other@example.com" }, 1),
+	(log) => log.sources(),
+];
+
+describe("cursedbelt-server/activity/d1", () => {
+	for (const [name, driver] of Object.entries(DRIVERS)) {
+		test(`🔴 parity over the ${name} driver: every page, count, facet and row match the sync log`, async () => {
+			const syncDb = new Database(":memory:");
+			const syncClock = clock();
+			const syncLog = createActivityLog({
+				db: syncDb,
+				app: APP,
+				now: syncClock,
+				sources: [shareEventsSource({ app: APP })],
+			});
+			const syncShares = createShareStore({ db: syncDb, app: APP, now: syncClock });
+
+			const d1Sqlite = withDdl(SHARE_DDL, ACTIVITY_DDL);
+			const d1 = driver(d1Sqlite);
+			const d1Clock = clock();
+			const d1Log = createD1ActivityLog({ db: d1, app: APP, now: d1Clock, sources: [shareEventsSource({ app: APP })] });
+			const d1Shares = createD1ShareStore({ db: d1, app: APP, now: d1Clock });
+
+			const grantVia =
+				(shares: { grant: (input: Parameters<typeof syncShares.grant>[0]) => unknown }): Grant =>
+				(email) =>
+					shares.grant({ kind: "person", id: "a", subject: user(email), level: "read", grantedBy: "curt@example.com" });
+
+			for (const [index, step] of SCENARIO.entries()) {
+				const expected = step(syncLog, grantVia(syncShares));
+				const actual = await step(d1Log, grantVia(d1Shares));
+				expect({ step: index, result: actual }).toEqual({ step: index, result: expected });
+			}
+			const table = (db: Database) => db.query("SELECT * FROM activity_events ORDER BY event_id").all();
+			expect(table(d1Sqlite)).toEqual(table(syncDb));
+			// Not vacuous: the merged stream really carried both contributors.
+			const merged = (await d1Log.query()).events.map((e) => e.source);
+			expect(new Set(merged)).toEqual(new Set(["log", "share"]));
+		});
+	}
+
+	test("ACTIVITY_DDL builds exactly the table and indexes the sync migration does", () => {
+		const shape = (db: Database) =>
+			db
+				.query("SELECT type, name, sql FROM sqlite_master WHERE name LIKE '%activity%' AND sql IS NOT NULL ORDER BY name")
+				.all();
+		const migrated = new Database(":memory:");
+		runMigrations(migrated, ACTIVITY_MIGRATIONS);
+		expect(shape(withDdl(ACTIVITY_DDL))).toEqual(shape(migrated));
+		expect(shape(migrated).length).toBe(5);
+	});
+
+	test("🔴 refuses an event that cannot be filtered or attributed, and writes nothing", async () => {
+		const sqlite = withDdl(ACTIVITY_DDL);
+		const log = createD1ActivityLog({ db: local(sqlite), app: "admin" });
+		await expect(log.record({ actor: "curt@example.com", action: "Backup Deleted" })).rejects.toThrow(/not an action/);
+		await expect(log.record({ actor: "curt@example.com", action: "backup" })).rejects.toThrow(/not an action/);
+		await expect(log.record({ actor: "   ", action: "backup.delete" })).rejects.toThrow(/no actor/);
+		expect(await log.count()).toBe(0);
+	});
+
+	test("is append only — no verb here can remove an event", () => {
+		const log = createD1ActivityLog({ db: local(withDdl(ACTIVITY_DDL)), app: "admin" });
+		expect(Object.keys(log).some((verb) => /delete|remove|purge|clear|prune|truncate/i.test(verb))).toBe(false);
+		expect(Object.keys(log).sort()).toEqual(
+			Object.keys(createActivityLog({ db: new Database(":memory:"), app: "admin" })).sort(),
+		);
+	});
+
+	test("a source whose table does not exist is empty, not a crash — and joins once it does", async () => {
+		const sqlite = withDdl(ACTIVITY_DDL);
+		const log = createD1ActivityLog({ db: local(sqlite), app: "notes", sources: [shareEventsSource({ app: "notes" })] });
+		await log.record({ actor: "curt@example.com", action: "note.create" });
+		expect(await log.sources()).toEqual(["log"]);
+		expect((await log.query()).events).toHaveLength(1);
+		expect((await log.facets()).actions).toHaveLength(1);
+		for (const statement of SHARE_DDL) sqlite.run(statement);
+		expect(await log.sources()).toEqual(["log", "share"]);
+	});
+
+	test("🔴 runs no DDL: on a database without the table it creates nothing and fails loudly", async () => {
+		const sqlite = new Database(":memory:");
+		const log = createD1ActivityLog({ db: local(sqlite), app: "notes" });
+		expect(sqlite.query("SELECT COUNT(*) AS n FROM sqlite_master").get()).toEqual({ n: 0 });
+		await expect(log.record({ actor: "curt@example.com", action: "note.create" })).rejects.toThrow(/no such table/);
+	});
+});

package/src/server/activity/d1.ts

@@ -0,0 +1,172 @@
+/**
+ * `cursedbelt-server/activity/d1` — the fleet's append-only activity stream over D1, for an app
+ * a Worker serves.
+ *
+ * ── Why it exists ───────────────────────────────────────────────────────────
+ * `./store.ts` is synchronous `bun:sqlite`; a Worker has neither. `apps/family`'s port to a
+ * Worker + D1 (task 393) needs the SAME stream — one append-only `activity_events` table plus
+ * read-only sources such as `share_events`, queried as one list — so this is that log, beside
+ * the sync one, which stays exactly as it was (`auth` and `roms` are still Bun servers).
+ *
+ * ── What is the same, and what is not ─────────────────────────────────────
+ * The same five verbs as `ActivityLog` — `record`, `query`, `count`, `facets`, `sources` —
+ * with the same validation, table, columns, filters, paging, ordering and source merge; each
+ * resolves instead of returning. The contract and every statement are the sync log's own
+ * (`./query.ts`), and `./d1.spec.ts` runs both logs through one scenario and compares them.
+ *
+ *   · Validation failures REJECT rather than throw synchronously (they are async methods).
+ *   · `sources()` is async too: "is this source's table there" is a query.
+ *   · 🔴 No DDL runs here, ever. The sync log migrates on construction; on D1 the table comes
+ *     from the app's `db/schema.sql`, built from {@link ACTIVITY_DDL} — the exact statements
+ *     the sync migration runs.
+ *
+ * A page costs one query per registered source (the table-exists probe, which is what keeps
+ * "a missing source table is an empty source" true) plus one for the page itself.
+ *
+ * 🔴 Worker-safe: nothing reachable from here at runtime imports `bun:*`
+ * (`../telemetryIsWorkerSafe.spec.ts` walks it). Do not import `./store.js` or
+ * `./migrations.js` here.
+ *
+ * ```ts
+ * import { createD1ActivityLog, shareEventsSource } from "cursedbelt-server/activity/d1";
+ *
+ * const activity = createD1ActivityLog({ db, app: "family", sources: [shareEventsSource({ app: "family" })] });
+ * await activity.record({ actor: viewer.email, action: "person.delete", resource: { kind: "person", id } });
+ * const page = await activity.query({ action: "share.", limit: 50 });
+ * ```
+ */
+import type { ActivityEvent, ActivityEventInput } from "cursedbelt-core/activity/model";
+import type { D1LikeBindable, D1LikeDatabase } from "../d1/types.js";
+import {
+	ACTIVITY_SQL,
+	type ActivityFacet,
+	type ActivityFacets,
+	type ActivityPage,
+	type ActivityQuery,
+	type ActivitySource,
+	buildStream,
+	facetLimit,
+	MAX_FACET,
+	pageLimit,
+	prepareRecord,
+	type StreamRow,
+	toStreamEvent,
+} from "./query.js";
+
+export { ACTIVITY_DDL, ACTIVITY_EVENTS_TABLE } from "./schema.js";
+export { shareEventsSource, type ShareEventsSourceOptions } from "./shareSource.js";
+export type {
+	ActivityBindable,
+	ActivityFacet,
+	ActivityFacets,
+	ActivityPage,
+	ActivityQuery,
+	ActivitySource,
+} from "./query.js";
+
+export interface D1ActivityLogOptions {
+	/** The app's D1 handle — `createRemoteD1(env.DB)` on a Worker, `createLocalD1(sqlite)` in a test. */
+	db: D1LikeDatabase;
+	/** The satellite this log speaks for. Fixed at construction, as in the sync log. */
+	app: string;
+	/** Read-only contributors merged into the stream. */
+	sources?: readonly ActivitySource[];
+	/** Injectable clock, ISO-8601. */
+	now?: () => string;
+}
+
+/** `ActivityLog`, over an async database — every verb resolves. */
+export interface AsyncActivityLog {
+	/** The app this log speaks for. */
+	readonly app: string;
+	/** Append one event. Resolves to it as it will be read back. */
+	record(input: ActivityEventInput): Promise<ActivityEvent>;
+	/** Newest first, bounded. */
+	query(query?: ActivityQuery): Promise<ActivityPage>;
+	/** How many events match — the unbounded count behind a bounded page. */
+	count(query?: ActivityQuery): Promise<number>;
+	/** What is in the result, per dimension, for a filter UI. */
+	facets(query?: ActivityQuery, limit?: number): Promise<ActivityFacets>;
+	/** Which contributors are live right now. */
+	sources(): Promise<string[]>;
+}
+
+/** The activity log over D1. Runs no DDL — see the header. */
+export function createD1ActivityLog(options: D1ActivityLogOptions): AsyncActivityLog {
+	const { db, app } = options;
+	const now = options.now ?? (() => new Date().toISOString());
+	const registered = options.sources ?? [];
+
+	const liveSources = async (): Promise<ActivitySource[]> => {
+		const live: ActivitySource[] = [];
+		for (const source of registered) {
+			if (
+				!source.requiresTable ||
+				(await db.prepare(ACTIVITY_SQL.tableExists).bind(source.requiresTable).first()) !== null
+			) {
+				live.push(source);
+			}
+		}
+		return live;
+	};
+
+	const stream = async (query: ActivityQuery): Promise<{ sql: string; params: D1LikeBindable[] }> =>
+		buildStream(query, await liveSources());
+
+	return {
+		app,
+
+		async record(input: ActivityEventInput): Promise<ActivityEvent> {
+			const { binds, event } = prepareRecord(app, input, now);
+			const result = await db
+				.prepare(ACTIVITY_SQL.insert)
+				.bind(...binds)
+				.run();
+			if (result.meta.last_row_id === null) {
+				throw new Error(`activity: the database reported no row id for ${input.action}`);
+			}
+			return { id: `log:${result.meta.last_row_id}`, ...event };
+		},
+
+		async query(query: ActivityQuery = {}): Promise<ActivityPage> {
+			const limit = pageLimit(query.limit);
+			const { sql, params } = await stream(query);
+			const { results: rows } = await db
+				.prepare(ACTIVITY_SQL.page(sql))
+				.bind(...params, limit + 1)
+				.all<StreamRow>();
+			const truncated = rows.length > limit;
+			return { events: rows.slice(0, limit).map(toStreamEvent), limit, truncated };
+		},
+
+		async count(query: ActivityQuery = {}): Promise<number> {
+			const { sql, params } = await stream(query);
+			const row = await db
+				.prepare(ACTIVITY_SQL.count(sql))
+				.bind(...params)
+				.first<{ n: number }>();
+			return row?.n ?? 0;
+		},
+
+		async facets(query: ActivityQuery = {}, limit = MAX_FACET): Promise<ActivityFacets> {
+			const { sql, params } = await stream(query);
+			const capped = facetLimit(limit);
+			const dimension = async (column: "action" | "actor" | "kind"): Promise<ActivityFacet[]> =>
+				(
+					await db
+						.prepare(ACTIVITY_SQL.facet(sql, column))
+						.bind(...params, capped)
+						.all<{ value: string; count: number }>()
+				).results.map((row) => ({ value: row.value, count: row.count }));
+			return {
+				actions: await dimension("action"),
+				actors: await dimension("actor"),
+				kinds: await dimension("kind"),
+			};
+		},
+
+		async sources(): Promise<string[]> {
+			return ["log", ...(await liveSources()).map((source) => source.name)];
+		},
+	};
+}

package/src/server/activity/migrations.ts

@@ -1,9 +1,11 @@
 import type { Database } from "bun:sqlite";
 import type { Migration } from "../migration/types.js";
+import { ACTIVITY_DDL } from "./schema.js";
 
-/** The one table this primitive owns. Exported so an app can declare a retention
- *  target over it (see this module's `index.ts` for the recipe). */
-export const ACTIVITY_EVENTS_TABLE = "activity_events";
+// The name and the DDL live in `./schema.ts`, driver-free, so a D1 app builds its schema file
+// from the SAME statements this migration runs (`cursedbelt-server/activity/d1` re-exports
+// them). Re-exported here so every existing import of this module keeps working.
+export { ACTIVITY_DDL, ACTIVITY_EVENTS_TABLE } from "./schema.js";
 
 /**
  * ONE append-only table per app, not a shadow table per business table.
@@ -25,43 +27,7 @@ export const ACTIVITY_MIGRATIONS: readonly Migration[] = [
 	{
 		name: "0001_activity_events",
 		up(db: Database): void {
-			db.run(`
-				CREATE TABLE IF NOT EXISTS ${ACTIVITY_EVENTS_TABLE} (
-					event_id    INTEGER PRIMARY KEY AUTOINCREMENT,
-					at          TEXT NOT NULL,
-					app         TEXT NOT NULL,
-					actor       TEXT NOT NULL,
-					action      TEXT NOT NULL,
-					kind        TEXT,
-					resource_id TEXT,
-					outcome     TEXT NOT NULL DEFAULT 'ok'
-					            CHECK (outcome IN ('ok', 'denied', 'error')),
-					note        TEXT NOT NULL DEFAULT '',
-					data        TEXT
-				)
-			`);
-			// The stream itself, newest first — the read every screen starts from.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_activity_events_at
-				 ON ${ACTIVITY_EVENTS_TABLE} (at DESC, event_id DESC)`,
-			);
-			// "Everything this person did" — the offboarding and the who-broke-it
-			// question, and the one a fleet-wide search runs first.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_activity_events_actor
-				 ON ${ACTIVITY_EVENTS_TABLE} (actor, event_id DESC)`,
-			);
-			// "Everything that ever happened to this record."
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_activity_events_resource
-				 ON ${ACTIVITY_EVENTS_TABLE} (kind, resource_id, event_id DESC)`,
-			);
-			// "Everything backups ever did" — an action-prefix filter is a range
-			// scan on this index, which is why the vocabulary is dotted.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_activity_events_action
-				 ON ${ACTIVITY_EVENTS_TABLE} (action, event_id DESC)`,
-			);
+			for (const statement of ACTIVITY_DDL) db.run(statement);
 		},
 	},
 ];