cursedbelt-server 4.26.1 → 4.28.0

package/src/server/activity/query.ts

@@ -0,0 +1,283 @@
+/**
+ * The activity stream's contract and SQL with no driver attached — ONE copy for both the
+ * `bun:sqlite` log (`./store.ts`) and the D1 log (`./d1.ts`).
+ *
+ * The two logs differ only in how they execute a statement. What an event looks like, how a
+ * source joins the union, what each filter means, how a page is bounded and how a facet is
+ * counted are all decided here, once — so "an action ending in a dot is a prefix" cannot be
+ * true on the Mac and false on a Worker. Driver-free on purpose: `./d1.ts` runs on `workerd`.
+ */
+import {
+	type ActivityEvent,
+	type ActivityEventInput,
+	type ActivityOutcome,
+	isActivityAction,
+	isActivityOutcome,
+} from "cursedbelt-core/activity/model";
+import { ACTIVITY_EVENTS_TABLE } from "./schema.js";
+
+/**
+ * A value a source may bind. The intersection of what `bun:sqlite` and D1 both accept, so a
+ * source written once contributes to either log.
+ */
+export type ActivityBindable = string | number | bigint | boolean | null | Uint8Array;
+
+/**
+ * A read-only stream contributor: a SELECT projecting some other table into the
+ * union's eleven columns, in this order and with these names —
+ *
+ *   `source, seq, at, app, actor, action, kind, resource_id, outcome, note, data`
+ *
+ * `seq` is that table's own row id: it breaks ties within one `at`, and it is
+ * what makes the event id (`"<source>:<seq>"`) stable and unique across sources.
+ */
+export interface ActivitySource {
+	/** Short, stable, unique within the log — it prefixes every id it produces. */
+	name: string;
+	/** The projection. See the column contract above. */
+	sql: string;
+	/** Bound in order, before any filter parameter. */
+	params?: readonly ActivityBindable[];
+	/**
+	 * A table this projection needs. When it does not exist the source is skipped
+	 * for that call rather than throwing — see property 3 in `./store.ts`'s header.
+	 */
+	requiresTable?: string;
+}
+
+/** Everything the stream can be narrowed by. Every field is optional; the empty
+ *  query is "the newest `limit` events". */
+export interface ActivityQuery {
+	/** ISO-8601, inclusive. */
+	since?: string;
+	/** ISO-8601, inclusive. */
+	until?: string;
+	/** Case-insensitive exact match on the account. */
+	actor?: string;
+	/** Exact, or a PREFIX when it ends in a dot: `"share."` matches `share.grant`. */
+	action?: string;
+	kind?: string;
+	resourceId?: string;
+	outcome?: ActivityOutcome;
+	/** Restrict to one contributor (`"log"`, `"share"`). */
+	source?: string;
+	/** Substring, over actor + action + note + resource id. */
+	q?: string;
+	/** Default 100, hard cap 1000. */
+	limit?: number;
+}
+
+export interface ActivityPage {
+	events: ActivityEvent[];
+	/** The limit actually applied, after defaulting and capping. */
+	limit: number;
+	/** There is at least one more row older than the last one returned. */
+	truncated: boolean;
+}
+
+/** One dimension of "what is in this result", for the filter UI. */
+export interface ActivityFacet {
+	value: string;
+	count: number;
+}
+
+export interface ActivityFacets {
+	actions: ActivityFacet[];
+	actors: ActivityFacet[];
+	kinds: ActivityFacet[];
+}
+
+export interface StreamRow {
+	source: string;
+	seq: number;
+	at: string;
+	app: string;
+	actor: string;
+	action: string;
+	kind: string | null;
+	resource_id: string | null;
+	outcome: ActivityOutcome;
+	note: string;
+	data: string | null;
+}
+
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+export const MAX_FACET = 25;
+
+/** `%` and `_` are wildcards and `\` is the escape — a note containing any of
+ *  them must still search literally. */
+const likeContains = (value: string): string => `%${value.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
+
+export const toStreamEvent = (row: StreamRow): ActivityEvent => ({
+	id: `${row.source}:${row.seq}`,
+	source: row.source,
+	at: row.at,
+	app: row.app,
+	actor: row.actor,
+	action: row.action,
+	resource:
+		row.kind === null || row.resource_id === null ? null : { app: row.app, kind: row.kind, id: row.resource_id },
+	outcome: isActivityOutcome(row.outcome) ? row.outcome : "ok",
+	note: row.note ?? "",
+	data: parseData(row.data),
+});
+
+/** A row whose `data` is unreadable must not take the page down with it — the
+ *  event still says who did what, which is the part that matters. */
+function parseData(raw: string | null): Record<string, unknown> | null {
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw) as unknown;
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: { value: parsed };
+	} catch {
+		return { unparsed: raw };
+	}
+}
+
+export const ACTIVITY_SQL = {
+	/** Binds at, app, actor, action, kind, resource_id, outcome, note, data. */
+	insert: `INSERT INTO ${ACTIVITY_EVENTS_TABLE}
+		   (at, app, actor, action, kind, resource_id, outcome, note, data)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+	tableExists: "SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?",
+	ownSelect: `SELECT 'log' AS source, event_id AS seq, at, app, actor, action,
+	                           kind, resource_id, outcome, note, data
+	                      FROM ${ACTIVITY_EVENTS_TABLE}`,
+	/** One row past the limit, so "there is more" is a fact rather than a guess made from
+	 *  `rows.length === limit`. Binds the stream's params, then `limit + 1`. */
+	page: (stream: string): string => `${stream} ORDER BY at DESC, seq DESC LIMIT ?`,
+	count: (stream: string): string => `SELECT COUNT(*) AS n FROM (${stream})`,
+	/** Binds the stream's params, then the facet cap. `column` is one of three literals. */
+	facet: (stream: string, column: "action" | "actor" | "kind"): string =>
+		`SELECT ${column} AS value, COUNT(*) AS count FROM (${stream})
+							  WHERE ${column} IS NOT NULL AND ${column} <> ''
+							  GROUP BY ${column} ORDER BY count DESC, value ASC LIMIT ?`,
+} as const;
+
+/** The limit a page actually applies: default 100, never above 1000 or below 1. */
+export const pageLimit = (limit: number | undefined): number =>
+	Math.min(MAX_LIMIT, Math.max(1, Math.floor(limit ?? DEFAULT_LIMIT)));
+
+/** The facet cap: default {@link MAX_FACET}, never above it or below 1. */
+export const facetLimit = (limit: number): number => Math.min(MAX_FACET, Math.max(1, Math.floor(limit)));
+
+/**
+ * The union of the log's own rows and every LIVE source, plus the WHERE the caller asked for,
+ * plus their parameters in bind order (sources first — they are inside the FROM).
+ */
+export function buildStream(
+	query: ActivityQuery,
+	liveSources: readonly ActivitySource[],
+): { sql: string; params: ActivityBindable[] } {
+	const params: ActivityBindable[] = [];
+	const selects: string[] = [ACTIVITY_SQL.ownSelect];
+	for (const source of liveSources) {
+		if (query.source && query.source !== source.name) continue;
+		selects.push(source.sql);
+		params.push(...(source.params ?? []));
+	}
+	const where: string[] = [];
+	if (query.source) {
+		where.push("source = ?");
+		params.push(query.source);
+	}
+	if (query.since) {
+		where.push("at >= ?");
+		params.push(query.since);
+	}
+	if (query.until) {
+		where.push("at <= ?");
+		params.push(query.until);
+	}
+	if (query.actor) {
+		where.push("LOWER(actor) = LOWER(?)");
+		params.push(query.actor);
+	}
+	if (query.action) {
+		if (query.action.endsWith(".")) {
+			where.push("action LIKE ? ESCAPE '\\'");
+			params.push(`${query.action.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`);
+		} else {
+			where.push("action = ?");
+			params.push(query.action);
+		}
+	}
+	if (query.kind) {
+		where.push("kind = ?");
+		params.push(query.kind);
+	}
+	if (query.resourceId) {
+		where.push("resource_id = ?");
+		params.push(query.resourceId);
+	}
+	if (query.outcome) {
+		where.push("outcome = ?");
+		params.push(query.outcome);
+	}
+	if (query.q) {
+		where.push(
+			"(actor LIKE ? ESCAPE '\\' OR action LIKE ? ESCAPE '\\' OR note LIKE ? ESCAPE '\\' OR IFNULL(resource_id, '') LIKE ? ESCAPE '\\')",
+		);
+		const like = likeContains(query.q);
+		params.push(like, like, like, like);
+	}
+	// `query.source` naming a contributor that is not live leaves only the own
+	// select, filtered to a source it cannot be — an empty result, which is the
+	// honest answer rather than every row.
+	const sql = `SELECT * FROM (${selects.join("\n UNION ALL\n")}) AS stream${
+		where.length ? ` WHERE ${where.join(" AND ")}` : ""
+	}`;
+	return { sql, params };
+}
+
+/**
+ * Validate one event for the write and return the row to bind plus the event as it will be
+ * read back (minus its id, which only the insert can know). Throws on an action that cannot be
+ * filtered or an event that cannot say who — property 4 of `./store.ts`'s header.
+ */
+export function prepareRecord(
+	app: string,
+	input: ActivityEventInput,
+	now: () => string,
+): { binds: [string, string, string, string, string | null, string | null, string, string, string | null]; event: Omit<ActivityEvent, "id"> } {
+	if (!isActivityAction(input.action)) {
+		throw new Error(
+			`activity: "${input.action}" is not an action — use lowercase subject.verb, e.g. "backup.delete"`,
+		);
+	}
+	const actor = input.actor?.trim();
+	if (!actor) {
+		// An event that cannot say who is a log line, not an audit trail.
+		throw new Error(`activity: ${input.action} has no actor`);
+	}
+	const at = input.at ?? now();
+	const outcome = input.outcome ?? "ok";
+	const data = input.data ? JSON.stringify(input.data) : null;
+	return {
+		binds: [
+			at,
+			app,
+			actor,
+			input.action,
+			input.resource?.kind ?? null,
+			input.resource?.id ?? null,
+			outcome,
+			input.note ?? "",
+			data,
+		],
+		event: {
+			source: "log",
+			at,
+			app,
+			actor,
+			action: input.action,
+			resource: input.resource ? { app, ...input.resource } : null,
+			outcome,
+			note: input.note ?? "",
+			data: input.data ?? null,
+		},
+	};
+}

package/src/server/activity/schema.ts

@@ -0,0 +1,45 @@
+/**
+ * The activity table's name and DDL, with no driver attached — the ONE copy both the
+ * `bun:sqlite` migration (`./migrations.ts`) and a D1 app's `db/schema.sql` are built from.
+ *
+ * Import-free on purpose: `./d1.ts` runs on `workerd`, and a Worker app generates its schema
+ * file from these statements rather than running DDL at request time. Why the table is ONE
+ * append-only stream is `./migrations.ts`'s header.
+ */
+
+/** 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";
+
+/** Every statement of the `0001_activity_events` migration, in order. Idempotent. */
+export const ACTIVITY_DDL: readonly string[] = [
+	`
+				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.
+	`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.
+	`CREATE INDEX IF NOT EXISTS idx_activity_events_actor
+				 ON ${ACTIVITY_EVENTS_TABLE} (actor, event_id DESC)`,
+	// "Everything that ever happened to this record."
+	`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.
+	`CREATE INDEX IF NOT EXISTS idx_activity_events_action
+				 ON ${ACTIVITY_EVENTS_TABLE} (action, event_id DESC)`,
+];

package/src/server/activity/shareSource.ts

@@ -25,8 +25,8 @@
  * fleet-wide board merges on that column and an unlabeled row would be
  * unattributable.
  */
-import { SHARE_EVENTS_TABLE } from "../sharing/migrations.js";
-import type { ActivitySource } from "./store.js";
+import { SHARE_EVENTS_TABLE } from "../sharing/schema.js";
+import type { ActivitySource } from "./query.js";
 
 export interface ShareEventsSourceOptions {
 	/** The satellite this log speaks for — the same value passed to

package/src/server/activity/store.ts

@@ -34,80 +34,36 @@
  *     cannot be filtered, and filtering is the whole point of the column.
  */
 import type { Database, SQLQueryBindings } from "bun:sqlite";
-import {
-	type ActivityEvent,
-	type ActivityEventInput,
-	type ActivityOutcome,
-	isActivityAction,
-	isActivityOutcome,
-} from "cursedbelt-core/activity/model";
+import type { ActivityEvent, ActivityEventInput } from "cursedbelt-core/activity/model";
 import { runMigrations } from "../migration/runner.js";
-import { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations.js";
-
-/**
- * A read-only stream contributor: a SELECT projecting some other table into the
- * union's eleven columns, in this order and with these names —
- *
- *   `source, seq, at, app, actor, action, kind, resource_id, outcome, note, data`
- *
- * `seq` is that table's own row id: it breaks ties within one `at`, and it is
- * what makes the event id (`"<source>:<seq>"`) stable and unique across sources.
- */
-export interface ActivitySource {
-	/** Short, stable, unique within the log — it prefixes every id it produces. */
-	name: string;
-	/** The projection. See the column contract above. */
-	sql: string;
-	/** Bound in order, before any filter parameter. */
-	params?: readonly SQLQueryBindings[];
-	/**
-	 * A table this projection needs. When it does not exist the source is skipped
-	 * for that call rather than throwing — see property 3 in the header.
-	 */
-	requiresTable?: string;
-}
-
-/** Everything the stream can be narrowed by. Every field is optional; the empty
- *  query is "the newest `limit` events". */
-export interface ActivityQuery {
-	/** ISO-8601, inclusive. */
-	since?: string;
-	/** ISO-8601, inclusive. */
-	until?: string;
-	/** Case-insensitive exact match on the account. */
-	actor?: string;
-	/** Exact, or a PREFIX when it ends in a dot: `"share."` matches `share.grant`. */
-	action?: string;
-	kind?: string;
-	resourceId?: string;
-	outcome?: ActivityOutcome;
-	/** Restrict to one contributor (`"log"`, `"share"`). */
-	source?: string;
-	/** Substring, over actor + action + note + resource id. */
-	q?: string;
-	/** Default 100, hard cap 1000. */
-	limit?: number;
-}
-
-export interface ActivityPage {
-	events: ActivityEvent[];
-	/** The limit actually applied, after defaulting and capping. */
-	limit: number;
-	/** There is at least one more row older than the last one returned. */
-	truncated: boolean;
-}
-
-/** One dimension of "what is in this result", for the filter UI. */
-export interface ActivityFacet {
-	value: string;
-	count: number;
-}
-
-export interface ActivityFacets {
-	actions: ActivityFacet[];
-	actors: ActivityFacet[];
-	kinds: ActivityFacet[];
-}
+import { ACTIVITY_MIGRATIONS } from "./migrations.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";
+
+// The contract and the SQL have no driver in them, so `./d1.ts` (which runs on `workerd`)
+// shares them without reaching this file. Re-exported so `cursedbelt-server/activity` is
+// unchanged.
+export type {
+	ActivityBindable,
+	ActivityFacet,
+	ActivityFacets,
+	ActivityPage,
+	ActivityQuery,
+	ActivitySource,
+} from "./query.js";
 
 export interface ActivityLogOptions {
 	db: Database;
@@ -136,59 +92,6 @@ export interface ActivityLog {
 	sources(): string[];
 }
 
-interface StreamRow {
-	source: string;
-	seq: number;
-	at: string;
-	app: string;
-	actor: string;
-	action: string;
-	kind: string | null;
-	resource_id: string | null;
-	outcome: ActivityOutcome;
-	note: string;
-	data: string | null;
-}
-
-const DEFAULT_LIMIT = 100;
-const MAX_LIMIT = 1000;
-const MAX_FACET = 25;
-
-/** `%` and `_` are wildcards and `\` is the escape — a note containing any of
- *  them must still search literally. */
-const likeContains = (value: string): string =>
-	`%${value.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
-
-const toEvent = (row: StreamRow): ActivityEvent => ({
-	id: `${row.source}:${row.seq}`,
-	source: row.source,
-	at: row.at,
-	app: row.app,
-	actor: row.actor,
-	action: row.action,
-	resource:
-		row.kind === null || row.resource_id === null
-			? null
-			: { app: row.app, kind: row.kind, id: row.resource_id },
-	outcome: isActivityOutcome(row.outcome) ? row.outcome : "ok",
-	note: row.note ?? "",
-	data: parseData(row.data),
-});
-
-/** A row whose `data` is unreadable must not take the page down with it — the
- *  event still says who did what, which is the part that matters. */
-function parseData(raw: string | null): Record<string, unknown> | null {
-	if (!raw) return null;
-	try {
-		const parsed = JSON.parse(raw) as unknown;
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-			? (parsed as Record<string, unknown>)
-			: { value: parsed };
-	} catch {
-		return { unparsed: raw };
-	}
-}
-
 export function createActivityLog(options: ActivityLogOptions): ActivityLog {
 	const { db, app } = options;
 	const now = options.now ?? (() => new Date().toISOString());
@@ -196,146 +99,37 @@ export function createActivityLog(options: ActivityLogOptions): ActivityLog {
 
 	runMigrations(db, ACTIVITY_MIGRATIONS);
 
-	const insert = db.query(
-		`INSERT INTO ${ACTIVITY_EVENTS_TABLE}
-		   (at, app, actor, action, kind, resource_id, outcome, note, data)
-		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-	);
+	const insert = db.query(ACTIVITY_SQL.insert);
 
-	const tableExists = (name: string): boolean =>
-		!!db
-			.query("SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?")
-			.get(name);
+	const tableExists = (name: string): boolean => !!db.query(ACTIVITY_SQL.tableExists).get(name);
 
 	/** The contributors that can actually answer right now. */
 	const liveSources = (): ActivitySource[] =>
 		registered.filter((source) => !source.requiresTable || tableExists(source.requiresTable));
 
-	const OWN_SELECT = `SELECT 'log' AS source, event_id AS seq, at, app, actor, action,
-	                           kind, resource_id, outcome, note, data
-	                      FROM ${ACTIVITY_EVENTS_TABLE}`;
-
-	/** The union, plus the WHERE the caller asked for, plus their parameters in
-	 *  bind order (sources first — they are inside the FROM). */
-	const stream = (query: ActivityQuery): { sql: string; params: SQLQueryBindings[] } => {
-		const params: SQLQueryBindings[] = [];
-		const selects = [OWN_SELECT];
-		for (const source of liveSources()) {
-			if (query.source && query.source !== source.name) continue;
-			selects.push(source.sql);
-			params.push(...(source.params ?? []));
-		}
-		const where: string[] = [];
-		if (query.source) {
-			where.push("source = ?");
-			params.push(query.source);
-		}
-		if (query.since) {
-			where.push("at >= ?");
-			params.push(query.since);
-		}
-		if (query.until) {
-			where.push("at <= ?");
-			params.push(query.until);
-		}
-		if (query.actor) {
-			where.push("LOWER(actor) = LOWER(?)");
-			params.push(query.actor);
-		}
-		if (query.action) {
-			if (query.action.endsWith(".")) {
-				where.push("action LIKE ? ESCAPE '\\'");
-				params.push(`${query.action.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`);
-			} else {
-				where.push("action = ?");
-				params.push(query.action);
-			}
-		}
-		if (query.kind) {
-			where.push("kind = ?");
-			params.push(query.kind);
-		}
-		if (query.resourceId) {
-			where.push("resource_id = ?");
-			params.push(query.resourceId);
-		}
-		if (query.outcome) {
-			where.push("outcome = ?");
-			params.push(query.outcome);
-		}
-		if (query.q) {
-			where.push(
-				"(actor LIKE ? ESCAPE '\\' OR action LIKE ? ESCAPE '\\' OR note LIKE ? ESCAPE '\\' OR IFNULL(resource_id, '') LIKE ? ESCAPE '\\')",
-			);
-			const like = likeContains(query.q);
-			params.push(like, like, like, like);
-		}
-		// `query.source` naming a contributor that is not live leaves only the own
-		// select, filtered to a source it cannot be — an empty result, which is the
-		// honest answer rather than every row.
-		const sql = `SELECT * FROM (${selects.join("\n UNION ALL\n")}) AS stream${
-			where.length ? ` WHERE ${where.join(" AND ")}` : ""
-		}`;
-		return { sql, params };
-	};
+	const stream = (query: ActivityQuery): { sql: string; params: SQLQueryBindings[] } =>
+		buildStream(query, liveSources());
 
 	return {
 		app,
 
 		record(input: ActivityEventInput): ActivityEvent {
-			if (!isActivityAction(input.action)) {
-				throw new Error(
-					`activity: "${input.action}" is not an action — use lowercase subject.verb, e.g. "backup.delete"`,
-				);
-			}
-			const actor = input.actor?.trim();
-			if (!actor) {
-				// An event that cannot say who is a log line, not an audit trail.
-				throw new Error(`activity: ${input.action} has no actor`);
-			}
-			const at = input.at ?? now();
-			const outcome = input.outcome ?? "ok";
-			const data = input.data ? JSON.stringify(input.data) : null;
-			const info = insert.run(
-				at,
-				app,
-				actor,
-				input.action,
-				input.resource?.kind ?? null,
-				input.resource?.id ?? null,
-				outcome,
-				input.note ?? "",
-				data,
-			);
-			return {
-				id: `log:${Number(info.lastInsertRowid)}`,
-				source: "log",
-				at,
-				app,
-				actor,
-				action: input.action,
-				resource: input.resource ? { app, ...input.resource } : null,
-				outcome,
-				note: input.note ?? "",
-				data: input.data ?? null,
-			};
+			const { binds, event } = prepareRecord(app, input, now);
+			const info = insert.run(...binds);
+			return { id: `log:${Number(info.lastInsertRowid)}`, ...event };
 		},
 
 		query(query: ActivityQuery = {}): ActivityPage {
-			const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DEFAULT_LIMIT)));
+			const limit = pageLimit(query.limit);
 			const { sql, params } = stream(query);
-			// One row past the limit, so "there is more" is a fact rather than a
-			// guess made from `rows.length === limit`.
-			const rows = db
-				.query(`${sql} ORDER BY at DESC, seq DESC LIMIT ?`)
-				.all(...params, limit + 1) as StreamRow[];
+			const rows = db.query(ACTIVITY_SQL.page(sql)).all(...params, limit + 1) as StreamRow[];
 			const truncated = rows.length > limit;
-			return { events: rows.slice(0, limit).map(toEvent), limit, truncated };
+			return { events: rows.slice(0, limit).map(toStreamEvent), limit, truncated };
 		},
 
 		count(query: ActivityQuery = {}): number {
 			const { sql, params } = stream(query);
-			const row = db.query(`SELECT COUNT(*) AS n FROM (${sql})`).get(...params) as {
+			const row = db.query(ACTIVITY_SQL.count(sql)).get(...params) as {
 				n: number;
 			} | null;
 			return row?.n ?? 0;
@@ -343,17 +137,11 @@ export function createActivityLog(options: ActivityLogOptions): ActivityLog {
 
 		facets(query: ActivityQuery = {}, limit = MAX_FACET): ActivityFacets {
 			const { sql, params } = stream(query);
-			const capped = Math.min(MAX_FACET, Math.max(1, Math.floor(limit)));
-			const dimension = (column: string): ActivityFacet[] =>
-				(
-					db
-						.query(
-							`SELECT ${column} AS value, COUNT(*) AS count FROM (${sql})
-							  WHERE ${column} IS NOT NULL AND ${column} <> ''
-							  GROUP BY ${column} ORDER BY count DESC, value ASC LIMIT ?`,
-						)
-						.all(...params, capped) as { value: string; count: number }[]
-				).map((row) => ({ value: row.value, count: row.count }));
+			const capped = facetLimit(limit);
+			const dimension = (column: "action" | "actor" | "kind"): ActivityFacet[] =>
+				(db.query(ACTIVITY_SQL.facet(sql, column)).all(...params, capped) as { value: string; count: number }[]).map(
+					(row) => ({ value: row.value, count: row.count }),
+				);
 			return {
 				actions: dimension("action"),
 				actors: dimension("actor"),