cursedbelt-server 1.0.0

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

@@ -0,0 +1,255 @@
+/**
+ * What this suite pins, in order of how much it costs to get wrong:
+ *
+ *  1. **The SQL projection and the TypeScript adapter agree.** `shareEventsSource`
+ *     and `activityFromShareEvent` are two implementations of ONE mapping, and a
+ *     shape that drifts is exactly the "second audit trail" this primitive exists
+ *     to prevent. The test compares them field for field on a real grant.
+ *  2. **A missing source table is an empty source.** An app can register the
+ *     sharing source before it has ever made a grant.
+ *  3. **Append only.** The store exposes no verb that removes an event.
+ *  4. **The filters mean what they say**, including the two that are easy to get
+ *     subtly wrong: a `%` in a search term is a literal, and an action prefix is
+ *     a prefix rather than a substring.
+ */
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+import { activityFromShareEvent } from "cursedbelt-core/activity/model";
+import { createShareStore, user } from "../sharing/store";
+import { shareEventsSource } from "./shareSource";
+import { createActivityLog } from "./store";
+
+const open = (): Database => new Database(":memory:");
+
+/** A clock that ticks one minute per call, so `at` ordering is deterministic. */
+function clock(startIso = "2026-08-11T00:00:00.000Z"): () => string {
+	let at = Date.parse(startIso);
+	return () => {
+		const value = new Date(at).toISOString();
+		at += 60_000;
+		return value;
+	};
+}
+
+describe("the activity log", () => {
+	test("records and reads back one event", () => {
+		const log = createActivityLog({ db: open(), app: "admin", now: clock() });
+		const written = log.record({
+			actor: "curt@example.com",
+			action: "backup.delete",
+			resource: { kind: "database", id: "notes.sqlite" },
+			note: "superseded",
+			data: { bytes: 4096 },
+		});
+
+		expect(written.id).toBe("log:1");
+		expect(written.source).toBe("log");
+		expect(written.app).toBe("admin");
+		expect(written.resource).toEqual({ app: "admin", kind: "database", id: "notes.sqlite" });
+
+		const page = log.query();
+		expect(page.events).toEqual([written]);
+		expect(page.truncated).toBe(false);
+		expect(page.limit).toBe(100);
+	});
+
+	test("refuses an event that cannot be filtered or attributed", () => {
+		const log = createActivityLog({ db: open(), app: "admin" });
+		expect(() => log.record({ actor: "curt@example.com", action: "Backup Deleted" })).toThrow(
+			/not an action/,
+		);
+		expect(() => log.record({ actor: "curt@example.com", action: "backup" })).toThrow(
+			/not an action/,
+		);
+		expect(() => log.record({ actor: "   ", action: "backup.delete" })).toThrow(/no actor/);
+	});
+
+	test("is append only — no verb here can remove an event", () => {
+		const log = createActivityLog({ db: open(), app: "admin" });
+		const verbs = Object.keys(log);
+		expect(verbs.some((verb) => /delete|remove|purge|clear|prune|truncate/i.test(verb))).toBe(
+			false,
+		);
+	});
+
+	test("newest first, bounded, and honest about there being more", () => {
+		const log = createActivityLog({ db: open(), app: "admin", now: clock() });
+		for (let i = 0; i < 5; i++) {
+			log.record({ actor: "curt@example.com", action: "backup.create", note: `#${i}` });
+		}
+		const page = log.query({ limit: 2 });
+		expect(page.events.map((e) => e.note)).toEqual(["#4", "#3"]);
+		expect(page.truncated).toBe(true);
+		expect(log.query({ limit: 99 }).truncated).toBe(false);
+		expect(log.count()).toBe(5);
+		// A limit past the cap is capped, never taken literally.
+		expect(log.query({ limit: 10_000 }).limit).toBe(1000);
+	});
+
+	test("filters: window, actor case, action prefix, resource, outcome", () => {
+		const log = createActivityLog({ db: open(), app: "notes", now: clock() });
+		log.record({ actor: "Curt@Example.com", action: "note.create", resource: { kind: "note", id: "a" } });
+		log.record({ actor: "other@example.com", action: "note.delete", resource: { kind: "note", id: "b" } });
+		log.record({ actor: "curt@example.com", action: "backup.create", outcome: "error" });
+
+		expect(log.query({ actor: "curt@example.com" }).events.map((e) => e.action)).toEqual([
+			"backup.create",
+			"note.create",
+		]);
+		// A trailing dot is a PREFIX; without it the match is exact.
+		expect(log.query({ action: "note." }).events).toHaveLength(2);
+		expect(log.query({ action: "note.create" }).events).toHaveLength(1);
+		expect(log.query({ kind: "note", resourceId: "b" }).events).toHaveLength(1);
+		expect(log.query({ outcome: "error" }).events).toHaveLength(1);
+		expect(log.query({ since: "2026-08-11T00:01:00.000Z" }).events).toHaveLength(2);
+		expect(log.query({ until: "2026-08-11T00:00:30.000Z" }).events).toHaveLength(1);
+	});
+
+	test("a wildcard in a search term is a literal", () => {
+		const log = createActivityLog({ db: open(), app: "notes", now: clock() });
+		log.record({ actor: "curt@example.com", action: "note.create", note: "100% done" });
+		log.record({ actor: "curt@example.com", action: "note.create", note: "nothing like it" });
+
+		expect(log.query({ q: "100%" }).events).toHaveLength(1);
+		// Were `%` a wildcard, "%d" would match both.
+		expect(log.query({ q: "%d" }).events).toHaveLength(0);
+		expect(log.query({ q: "note.create" }).events).toHaveLength(2);
+	});
+
+	test("facets say what is in the result, bounded", () => {
+		const log = createActivityLog({ db: open(), app: "notes", now: clock() });
+		log.record({ actor: "a@example.com", action: "note.create", resource: { kind: "note", id: "1" } });
+		log.record({ actor: "a@example.com", action: "note.create", resource: { kind: "note", id: "2" } });
+		log.record({ actor: "b@example.com", action: "note.delete", resource: { kind: "note", id: "1" } });
+
+		const facets = log.facets();
+		expect(facets.actions).toEqual([
+			{ value: "note.create", count: 2 },
+			{ value: "note.delete", count: 1 },
+		]);
+		expect(facets.actors[0]).toEqual({ value: "a@example.com", count: 2 });
+		expect(facets.kinds).toEqual([{ value: "note", count: 3 }]);
+		// A facet respects the filter it is drawn under.
+		expect(log.facets({ actor: "b@example.com" }).actions).toEqual([
+			{ value: "note.delete", count: 1 },
+		]);
+	});
+});
+
+describe("the sharing primitive as a source", () => {
+	test("a share event reaches the stream, mapped exactly as the vocabulary maps it", () => {
+		const db = open();
+		const at = clock();
+		const shares = createShareStore({ db, app: "family", now: at });
+		const log = createActivityLog({
+			db,
+			app: "family",
+			now: at,
+			sources: [shareEventsSource({ app: "family" })],
+		});
+
+		const grant = shares.grant({
+			kind: "person",
+			id: "3f2",
+			subject: user("Aunt@Example.com"),
+			level: "read",
+			grantedBy: "curt@example.com",
+			note: "she asked",
+		});
+		expect(grant.level).toBe("read");
+
+		const [event] = shares.events({ kind: "person", id: "3f2" });
+		expect(event).toBeDefined();
+		const expected = activityFromShareEvent(event);
+
+		const [streamed] = log.query().events;
+		expect(streamed).toBeDefined();
+		expect(streamed.source).toBe("share");
+		expect(streamed.id).toBe(`share:${event.id}`);
+		// 🔴 The pin: the SQL projection and the adapter are one mapping.
+		expect({
+			at: streamed.at,
+			actor: streamed.actor,
+			action: streamed.action,
+			resource: streamed.resource
+				? { kind: streamed.resource.kind, id: streamed.resource.id }
+				: null,
+			outcome: streamed.outcome,
+			note: streamed.note,
+			data: streamed.data,
+		}).toEqual({
+			at: expected.at as string,
+			actor: expected.actor,
+			action: expected.action,
+			resource: expected.resource ?? null,
+			outcome: expected.outcome ?? "ok",
+			note: expected.note ?? "",
+			data: expected.data ?? null,
+		});
+	});
+
+	test("a group event is labeled with the log's app rather than left unattributed", () => {
+		const db = open();
+		const shares = createShareStore({ db, app: "family", now: clock() });
+		const log = createActivityLog({
+			db,
+			app: "family",
+			sources: [shareEventsSource({ app: "family" })],
+		});
+		shares.createGroup({ id: "trustees", name: "The trustees", createdBy: "curt@example.com" });
+
+		const [event] = log.query().events;
+		expect(event.app).toBe("family");
+		expect(event.action).toBe("share.group.create");
+		expect(event.resource).toBeNull();
+	});
+
+	test("own events and share events interleave by time, newest first", () => {
+		const db = open();
+		const at = clock();
+		const shares = createShareStore({ db, app: "family", now: at });
+		const log = createActivityLog({
+			db,
+			app: "family",
+			now: at,
+			sources: [shareEventsSource({ app: "family" })],
+		});
+		log.record({ actor: "curt@example.com", action: "person.create", resource: { kind: "person", id: "1" } });
+		shares.grant({
+			kind: "person",
+			id: "1",
+			subject: user("aunt@example.com"),
+			level: "read",
+			grantedBy: "curt@example.com",
+		});
+		log.record({ actor: "curt@example.com", action: "person.update", resource: { kind: "person", id: "1" } });
+
+		expect(log.query().events.map((e) => e.action)).toEqual([
+			"person.update",
+			"share.grant",
+			"person.create",
+		]);
+		expect(log.query({ source: "share" }).events.map((e) => e.action)).toEqual(["share.grant"]);
+		expect(log.query({ source: "log" }).events).toHaveLength(2);
+		expect(log.count()).toBe(3);
+	});
+
+	test("a source whose table does not exist is empty, not a crash", () => {
+		const db = open();
+		const log = createActivityLog({
+			db,
+			app: "notes",
+			sources: [shareEventsSource({ app: "notes" })],
+		});
+		log.record({ actor: "curt@example.com", action: "note.create" });
+
+		// No sharing tables in this database at all.
+		expect(log.sources()).toEqual(["log"]);
+		expect(log.query().events).toHaveLength(1);
+		expect(log.facets().actions).toHaveLength(1);
+
+		// …and it joins the stream the moment the app starts sharing.
+		createShareStore({ db, app: "notes" });
+		expect(log.sources()).toEqual(["log", "share"]);
+	});
+});

package/src/server/activity/store.ts

@@ -0,0 +1,368 @@
+/**
+ * The activity store: one append-only table, plus any number of read-only
+ * SOURCES projected into the same shape, queried as one stream.
+ *
+ * ── How an app uses it ──────────────────────────────────────────────────────
+ * ```ts
+ * const activity = createActivityLog({
+ *   db,
+ *   app: "family",
+ *   // The sharing primitive already audits itself. Read those rows where they
+ *   // are instead of copying them — see `shareEventsSource`.
+ *   sources: [shareEventsSource()],
+ * });
+ *
+ * activity.record({ actor: viewer.email, action: "person.delete",
+ *                   resource: { kind: "person", id }, note: "duplicate" });
+ *
+ * activity.query({ since, actor, action: "share.", limit: 100 });
+ * ```
+ *
+ * ── 🔴 Four properties this file exists to guarantee ────────────────────────
+ *  1. **Append only.** No update verb, no delete verb, no `TRUNCATE`. Ageing
+ *     rows out is the fleet retention standard's job, through a declaration the
+ *     owner can see (`satellite-kit/retention`) — never a silent cutoff here.
+ *  2. **A source is READ, never copied.** `share_events` stays the canonical
+ *     sharing trail; this store selects from it. Two tables holding the same
+ *     audit rows is two tables that will one day disagree, and the one people
+ *     would trust is whichever the screen happened to read.
+ *  3. **A missing source table is an empty source, not a 500.** An app may
+ *     register `shareEventsSource()` before it has ever created a grant, and a
+ *     dashboard must not die on the app that has done nothing yet. (The same
+ *     lesson `orch`'s `plainjob_jobs` retention target learned at boot.)
+ *  4. **`action` is validated at the write.** An action vocabulary that drifts
+ *     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 { runMigrations } from "../migration/runner";
+import { ACTIVITY_EVENTS_TABLE, ACTIVITY_MIGRATIONS } from "./migrations";
+
+/**
+ * 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[];
+}
+
+export interface ActivityLogOptions {
+	db: Database;
+	/** The satellite this log speaks for. Fixed at construction, so a caller
+	 *  cannot write an event under another app's name. */
+	app: string;
+	/** Read-only contributors merged into the stream. */
+	sources?: readonly ActivitySource[];
+	/** Injectable clock, ISO-8601. */
+	now?: () => string;
+}
+
+export interface ActivityLog {
+	/** The app this log speaks for. */
+	readonly app: string;
+	/** Append one event. Returns it as it will be read back. */
+	record(input: ActivityEventInput): ActivityEvent;
+	/** Newest first, bounded. */
+	query(query?: ActivityQuery): ActivityPage;
+	/** How many events match — the unbounded count behind a bounded page. */
+	count(query?: ActivityQuery): number;
+	/** What is in the result, per dimension, for a filter UI. */
+	facets(query?: ActivityQuery, limit?: number): ActivityFacets;
+	/** Which contributors are live right now (a source whose table is missing is
+	 *  absent, which is what the read surface reports). */
+	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());
+	const registered = options.sources ?? [];
+
+	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 tableExists = (name: string): boolean =>
+		!!db
+			.query("SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?")
+			.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 };
+	};
+
+	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,
+			};
+		},
+
+		query(query: ActivityQuery = {}): ActivityPage {
+			const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DEFAULT_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 truncated = rows.length > limit;
+			return { events: rows.slice(0, limit).map(toEvent), limit, truncated };
+		},
+
+		count(query: ActivityQuery = {}): number {
+			const { sql, params } = stream(query);
+			const row = db.query(`SELECT COUNT(*) AS n FROM (${sql})`).get(...params) as {
+				n: number;
+			} | null;
+			return row?.n ?? 0;
+		},
+
+		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 }));
+			return {
+				actions: dimension("action"),
+				actors: dimension("actor"),
+				kinds: dimension("kind"),
+			};
+		},
+
+		sources(): string[] {
+			return ["log", ...liveSources().map((source) => source.name)];
+		},
+	};
+}