cursedbelt-server 4.26.1 → 4.28.0

package/src/server/sharing/migrations.ts

@@ -32,97 +32,24 @@
  */
 import type { Database } from "bun:sqlite";
 import type { Migration } from "../migration/types.js";
+import { SHARE_DDL } from "./schema.js";
 
-export const SHARE_GRANTS_TABLE = "share_grants";
-export const SHARE_GROUPS_TABLE = "share_groups";
-export const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
-export const SHARE_EVENTS_TABLE = "share_events";
+// The names 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/sharing/d1` re-exports
+// them). Re-exported here so every existing import of this module keeps working.
+export {
+	SHARE_DDL,
+	SHARE_EVENTS_TABLE,
+	SHARE_GRANTS_TABLE,
+	SHARE_GROUPS_TABLE,
+	SHARE_GROUP_MEMBERS_TABLE,
+} from "./schema.js";
 
 export const SHARE_MIGRATIONS: readonly Migration[] = [
 	{
 		name: "0001_share_grants",
 		up(db: Database): void {
-			db.run(`
-				CREATE TABLE IF NOT EXISTS ${SHARE_GRANTS_TABLE} (
-					grant_id    INTEGER PRIMARY KEY AUTOINCREMENT,
-					app         TEXT NOT NULL,
-					kind        TEXT NOT NULL,
-					resource_id TEXT NOT NULL,
-					subject_type TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
-					subject_id  TEXT NOT NULL,
-					level       TEXT NOT NULL CHECK (level IN ('read', 'write')),
-					granted_by  TEXT NOT NULL,
-					granted_at  TEXT NOT NULL,
-					note        TEXT NOT NULL DEFAULT '',
-					-- One grant per subject per resource. This is what makes raising
-					-- read to write an UPDATE the audit trail can describe, instead of
-					-- two rows where revoking one leaves access in place.
-					UNIQUE (app, kind, resource_id, subject_type, subject_id)
-				)
-			`);
-			// The hot read is the resolver's: "does this subject hold a grant on this
-			// row" — correlated per row of a list query, so it must be an index hit.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_share_grants_subject
-				 ON ${SHARE_GRANTS_TABLE} (subject_type, subject_id, app, kind, resource_id)`,
-			);
-			// …and the panel's: "who can see this record".
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_share_grants_resource
-				 ON ${SHARE_GRANTS_TABLE} (app, kind, resource_id)`,
-			);
-
-			db.run(`
-				CREATE TABLE IF NOT EXISTS ${SHARE_GROUPS_TABLE} (
-					group_id   TEXT PRIMARY KEY,
-					name       TEXT NOT NULL,
-					created_by TEXT NOT NULL,
-					created_at TEXT NOT NULL,
-					note       TEXT NOT NULL DEFAULT ''
-				)
-			`);
-
-			db.run(`
-				CREATE TABLE IF NOT EXISTS ${SHARE_GROUP_MEMBERS_TABLE} (
-					group_id   TEXT NOT NULL REFERENCES ${SHARE_GROUPS_TABLE} (group_id) ON DELETE CASCADE,
-					subject_id TEXT NOT NULL,
-					added_by   TEXT NOT NULL,
-					added_at   TEXT NOT NULL,
-					PRIMARY KEY (group_id, subject_id)
-				)
-			`);
-			// "Which groups is this person in" — read by every shared-row query.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_share_group_members_subject
-				 ON ${SHARE_GROUP_MEMBERS_TABLE} (subject_id)`,
-			);
-
-			db.run(`
-				CREATE TABLE IF NOT EXISTS ${SHARE_EVENTS_TABLE} (
-					event_id      INTEGER PRIMARY KEY AUTOINCREMENT,
-					at            TEXT NOT NULL,
-					action        TEXT NOT NULL,
-					app           TEXT,
-					kind          TEXT,
-					resource_id   TEXT,
-					subject_type  TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
-					subject_id    TEXT NOT NULL,
-					level         TEXT,
-					previous_level TEXT,
-					actor         TEXT NOT NULL,
-					note          TEXT NOT NULL DEFAULT ''
-				)
-			`);
-			// "Everything that ever happened to this record", newest first.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_share_events_resource
-				 ON ${SHARE_EVENTS_TABLE} (app, kind, resource_id, event_id DESC)`,
-			);
-			// "Everything this person was ever given" — the offboarding question.
-			db.run(
-				`CREATE INDEX IF NOT EXISTS idx_share_events_subject
-				 ON ${SHARE_EVENTS_TABLE} (subject_id, event_id DESC)`,
-			);
+			for (const statement of SHARE_DDL) db.run(statement);
 		},
 	},
 ];

package/src/server/sharing/router.ts

@@ -44,7 +44,7 @@
  */
 import type { Context, Hono } from 'hono';
 import type { ShareEvent, ShareGrant, ShareLevel } from 'cursedbelt-core/sharing/model';
-import type { ShareStore } from './store.js';
+import type { AwaitableShareStore } from './contract.js';
 
 /** The `group:` prefix that lets a group subject travel in a path segment. Exported so a
  *  client and a route cannot disagree about it. */
@@ -77,8 +77,12 @@ export interface ShareRouterOptions<V extends ShareRouterViewer> {
   base: string;
   /** The `kind` half of the store's `(app, kind, id)` triple. */
   kind: string;
-  /** The store. A function when it is per-request (a multi-tenant app). */
-  shares: ShareStore | ((c: Context) => ShareStore);
+  /**
+   * The store — the sync `ShareStore` or the D1 `AsyncShareStore` (`./sharing/d1`); every
+   * call is awaited, and awaiting a sync store's plain value changes nothing. A function
+   * when it is per-request (a multi-tenant app, or a Worker whose D1 handle is per request).
+   */
+  shares: AwaitableShareStore | ((c: Context) => AwaitableShareStore);
   /** Who is asking. Returning null refuses every route with 401. */
   viewerOf: (c: Context) => V | null;
   /**
@@ -89,7 +93,11 @@ export interface ShareRouterOptions<V extends ShareRouterViewer> {
   mustOwn: (c: Context, id: string, viewer: V) => Response | null | Promise<Response | null>;
   /** Extra fields folded into the READ payload beside `{grants, events}` — family's
    *  `labels`, life's `groups`. */
-  extra?: (c: Context, id: string, viewer: V) => Record<string, unknown>;
+  extra?: (
+    c: Context,
+    id: string,
+    viewer: V,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>;
   /** How many audit lines the read carries. Default 50. */
   trailLimit?: number;
 }
@@ -125,13 +133,13 @@ export function mountShareRoutes<V extends ShareRouterViewer>(
   options: ShareRouterOptions<V>,
 ): void {
   const { base, kind, viewerOf, mustOwn, extra, trailLimit = 50 } = options;
-  const storeOf = (c: Context): ShareStore =>
+  const storeOf = (c: Context): AwaitableShareStore =>
     typeof options.shares === 'function' ? options.shares(c) : options.shares;
 
   /** The three-step preamble every route shares: identity, id, ownership. */
   async function enter(
     c: Context,
-  ): Promise<{ refused: Response } | { id: string; viewer: V; shares: ShareStore }> {
+  ): Promise<{ refused: Response } | { id: string; viewer: V; shares: AwaitableShareStore }> {
     const viewer = viewerOf(c);
     if (!viewer) return { refused: c.json({ error: 'sign in first' }, 401) };
     const id = c.req.param('id') ?? '';
@@ -147,9 +155,11 @@ export function mountShareRoutes<V extends ShareRouterViewer>(
     const payload: ShareRoutesPayload & Record<string, unknown> = {
       // The store's own rows, straight through — the sharing panel consumes exactly
       // these, and a DTO in the middle is a place for a field to go missing.
-      grants: shares.listForResource({ kind, id }),
-      events: shares.events({ kind, id, limit: trailLimit }),
-      ...(extra ? extra(c, id, viewer) : {}),
+      // Awaited in this order — grants, trail, extra — which is the order the sync store
+      // was always read in.
+      grants: await shares.listForResource({ kind, id }),
+      events: await shares.events({ kind, id, limit: trailLimit }),
+      ...(extra ? await extra(c, id, viewer) : {}),
     };
     return c.json(payload);
   });
@@ -171,7 +181,7 @@ export function mountShareRoutes<V extends ShareRouterViewer>(
     if (body.level !== undefined && !isLevel(body.level)) {
       return c.json({ error: "level must be 'read' or 'write'" }, 400);
     }
-    const grant = shares.grant({
+    const grant = await shares.grant({
       kind,
       id,
       subject: { type: body.subject?.type === 'group' ? 'group' : 'user', id: subjectId },
@@ -188,7 +198,7 @@ export function mountShareRoutes<V extends ShareRouterViewer>(
     const { id, viewer, shares } = step;
     const raw = c.req.param('subject') ?? '';
     if (!raw.trim()) return c.json({ error: 'which share should be removed?' }, 400);
-    shares.revoke({ kind, id, subject: parseSubjectParam(raw), revokedBy: viewer.email });
+    await shares.revoke({ kind, id, subject: parseSubjectParam(raw), revokedBy: viewer.email });
     return c.json({ ok: true });
   });
 }

package/src/server/sharing/schema.ts

@@ -0,0 +1,90 @@
+/**
+ * The sharing tables' names 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.
+ *
+ * It is 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. The migration
+ * runs exactly this list, so the two can never describe different tables. Why each table and
+ * each index exists is `./migrations.ts`'s header.
+ */
+
+export const SHARE_GRANTS_TABLE = "share_grants";
+export const SHARE_GROUPS_TABLE = "share_groups";
+export const SHARE_GROUP_MEMBERS_TABLE = "share_group_members";
+export const SHARE_EVENTS_TABLE = "share_events";
+
+/**
+ * Every statement of the `0001_share_grants` migration, in order. Idempotent (`IF NOT
+ * EXISTS` throughout), so a schema file built from it can be applied to a database that
+ * already has the tables.
+ */
+export const SHARE_DDL: readonly string[] = [
+	`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GRANTS_TABLE} (
+					grant_id    INTEGER PRIMARY KEY AUTOINCREMENT,
+					app         TEXT NOT NULL,
+					kind        TEXT NOT NULL,
+					resource_id TEXT NOT NULL,
+					subject_type TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id  TEXT NOT NULL,
+					level       TEXT NOT NULL CHECK (level IN ('read', 'write')),
+					granted_by  TEXT NOT NULL,
+					granted_at  TEXT NOT NULL,
+					note        TEXT NOT NULL DEFAULT '',
+					-- One grant per subject per resource. This is what makes raising
+					-- read to write an UPDATE the audit trail can describe, instead of
+					-- two rows where revoking one leaves access in place.
+					UNIQUE (app, kind, resource_id, subject_type, subject_id)
+				)
+			`,
+	// The hot read is the resolver's: "does this subject hold a grant on this
+	// row" — correlated per row of a list query, so it must be an index hit.
+	`CREATE INDEX IF NOT EXISTS idx_share_grants_subject
+				 ON ${SHARE_GRANTS_TABLE} (subject_type, subject_id, app, kind, resource_id)`,
+	// …and the panel's: "who can see this record".
+	`CREATE INDEX IF NOT EXISTS idx_share_grants_resource
+				 ON ${SHARE_GRANTS_TABLE} (app, kind, resource_id)`,
+	`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUPS_TABLE} (
+					group_id   TEXT PRIMARY KEY,
+					name       TEXT NOT NULL,
+					created_by TEXT NOT NULL,
+					created_at TEXT NOT NULL,
+					note       TEXT NOT NULL DEFAULT ''
+				)
+			`,
+	`
+				CREATE TABLE IF NOT EXISTS ${SHARE_GROUP_MEMBERS_TABLE} (
+					group_id   TEXT NOT NULL REFERENCES ${SHARE_GROUPS_TABLE} (group_id) ON DELETE CASCADE,
+					subject_id TEXT NOT NULL,
+					added_by   TEXT NOT NULL,
+					added_at   TEXT NOT NULL,
+					PRIMARY KEY (group_id, subject_id)
+				)
+			`,
+	// "Which groups is this person in" — read by every shared-row query.
+	`CREATE INDEX IF NOT EXISTS idx_share_group_members_subject
+				 ON ${SHARE_GROUP_MEMBERS_TABLE} (subject_id)`,
+	`
+				CREATE TABLE IF NOT EXISTS ${SHARE_EVENTS_TABLE} (
+					event_id      INTEGER PRIMARY KEY AUTOINCREMENT,
+					at            TEXT NOT NULL,
+					action        TEXT NOT NULL,
+					app           TEXT,
+					kind          TEXT,
+					resource_id   TEXT,
+					subject_type  TEXT NOT NULL CHECK (subject_type IN ('user', 'group')),
+					subject_id    TEXT NOT NULL,
+					level         TEXT,
+					previous_level TEXT,
+					actor         TEXT NOT NULL,
+					note          TEXT NOT NULL DEFAULT ''
+				)
+			`,
+	// "Everything that ever happened to this record", newest first.
+	`CREATE INDEX IF NOT EXISTS idx_share_events_resource
+				 ON ${SHARE_EVENTS_TABLE} (app, kind, resource_id, event_id DESC)`,
+	// "Everything this person was ever given" — the offboarding question.
+	`CREATE INDEX IF NOT EXISTS idx_share_events_subject
+				 ON ${SHARE_EVENTS_TABLE} (subject_id, event_id DESC)`,
+];

package/src/server/sharing/sql.ts

@@ -26,7 +26,7 @@
  * tested with hostile input; a consumer never quotes anything itself.
  */
 import { levelsMeeting, normalizeSubjectId, type ShareLevel } from "cursedbelt-core/sharing/model";
-import { SHARE_GRANTS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./migrations.js";
+import { SHARE_GRANTS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./schema.js";
 
 /**
  * Quote a string as a SQL literal.

package/src/server/sharing/statements.ts

@@ -0,0 +1,213 @@
+/**
+ * Every SQL statement the share stores run, and the row → shape mappers — ONE copy for both
+ * the `bun:sqlite` store (`./store.ts`) and the D1 store (`./d1.ts`).
+ *
+ * Two stores with two copies of "strongest first, then oldest" is two answers the day
+ * somebody edits one of them. So the stores differ only in HOW they execute (a synchronous
+ * transaction vs one atomic `batch()`), never in WHAT they ask. Driver-free on purpose: the
+ * D1 store runs on `workerd`.
+ */
+import type { ShareAction, ShareEvent, ShareGrant, ShareLevel } from "cursedbelt-core/sharing/model";
+import { SHARE_EVENTS_TABLE, SHARE_GRANTS_TABLE, SHARE_GROUPS_TABLE, SHARE_GROUP_MEMBERS_TABLE } from "./schema.js";
+
+export interface GrantRow {
+	app: string;
+	kind: string;
+	resource_id: string;
+	subject_type: "user" | "group";
+	subject_id: string;
+	level: ShareLevel;
+	granted_by: string;
+	granted_at: string;
+	note: string;
+}
+
+export interface EventRow {
+	event_id: number;
+	at: string;
+	action: ShareAction;
+	app: string | null;
+	kind: string | null;
+	resource_id: string | null;
+	subject_type: "user" | "group";
+	subject_id: string;
+	level: ShareLevel | null;
+	previous_level: ShareLevel | null;
+	actor: string;
+	note: string;
+}
+
+export interface GroupRow {
+	group_id: string;
+	name: string;
+	created_by: string;
+	created_at: string;
+	note: string;
+}
+
+export interface GroupMemberRow {
+	group_id: string;
+	subject_id: string;
+	added_by: string;
+	added_at: string;
+}
+
+export const toGrant = (row: GrantRow): ShareGrant => ({
+	resource: { app: row.app, kind: row.kind, id: row.resource_id },
+	subject: { type: row.subject_type, id: row.subject_id },
+	level: row.level,
+	grantedBy: row.granted_by,
+	grantedAt: row.granted_at,
+	note: row.note,
+});
+
+export const toEvent = (row: EventRow): ShareEvent => ({
+	id: row.event_id,
+	at: row.at,
+	action: row.action,
+	resource:
+		row.app === null || row.kind === null || row.resource_id === null
+			? null
+			: { app: row.app, kind: row.kind, id: row.resource_id },
+	subject: { type: row.subject_type, id: row.subject_id },
+	level: row.level,
+	previousLevel: row.previous_level,
+	actor: row.actor,
+	note: row.note,
+});
+
+/** The audit trail's columns, in the order every event insert binds them. */
+const EVENT_COLUMNS =
+	"(at, action, app, kind, resource_id, subject_type, subject_id, level, previous_level, actor, note)";
+
+/** One grant row's WHERE — the five columns of its UNIQUE key. */
+const ONE_GRANT = "app = ? AND kind = ? AND resource_id = ? AND subject_type = ? AND subject_id = ?";
+const RESOURCE_GRANTS = "app = ? AND kind = ? AND resource_id = ?";
+const SUBJECT_GRANTS = "app = ? AND subject_type = ? AND subject_id = ?";
+const GROUP_GRANTS = "app = ? AND subject_type = 'group' AND subject_id = ?";
+
+/** "This viewer, directly or through any group they are in" — binds `subjectId` twice. */
+const VIEWER_MATCH = `( (subject_type = 'user' AND subject_id = ?)
+		      OR (subject_type = 'group' AND subject_id IN
+		          (SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ?)) )`;
+
+export const SHARE_SQL = {
+	/** Binds the eleven {@link EVENT_COLUMNS}. */
+	insertEvent: `INSERT INTO ${SHARE_EVENTS_TABLE}
+			   ${EVENT_COLUMNS}
+			 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+
+	selectGrant: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${ONE_GRANT}`,
+	/** Binds app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note. */
+	upsertGrant: `INSERT INTO ${SHARE_GRANTS_TABLE}
+				   (app, kind, resource_id, subject_type, subject_id, level, granted_by, granted_at, note)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT (app, kind, resource_id, subject_type, subject_id)
+				 DO UPDATE SET level = excluded.level, granted_by = excluded.granted_by,
+				               granted_at = excluded.granted_at, note = excluded.note`,
+	deleteGrant: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${ONE_GRANT}`,
+
+	selectResourceGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${RESOURCE_GRANTS}`,
+	deleteResourceGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${RESOURCE_GRANTS}`,
+	selectSubjectGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${SUBJECT_GRANTS}`,
+	deleteSubjectGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${SUBJECT_GRANTS}`,
+	selectGroupGrants: `SELECT * FROM ${SHARE_GRANTS_TABLE} WHERE ${GROUP_GRANTS}`,
+	deleteGroupGrants: `DELETE FROM ${SHARE_GRANTS_TABLE} WHERE ${GROUP_GRANTS}`,
+
+	listForResource: `SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${RESOURCE_GRANTS}
+					 -- Strongest first, then oldest. Spelled as a CASE rather than an
+					 -- ORDER BY on level, which happens to work only because 'write'
+					 -- sorts after 'read' and would silently mis-order a third level.
+					 ORDER BY CASE level WHEN 'write' THEN 0 ELSE 1 END, granted_at ASC`,
+	listForSubject: `SELECT * FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${SUBJECT_GRANTS}
+					 ORDER BY granted_at DESC`,
+	/** Binds app, kind, resource_id, then the viewer twice. */
+	accessFor: `SELECT level FROM ${SHARE_GRANTS_TABLE}
+					 WHERE ${RESOURCE_GRANTS}
+					   AND ${VIEWER_MATCH}`,
+	/** Binds app, kind, each of `levelCount` levels, then the viewer twice. */
+	resourceIdsFor: (levelCount: number): string => `SELECT DISTINCT resource_id FROM ${SHARE_GRANTS_TABLE}
+					 WHERE app = ? AND kind = ? AND level IN (${Array.from({ length: levelCount }, () => "?").join(", ")})
+					   AND ${VIEWER_MATCH}
+					 ORDER BY resource_id`,
+
+	upsertGroup: `INSERT INTO ${SHARE_GROUPS_TABLE} (group_id, name, created_by, created_at, note)
+					 VALUES (?, ?, ?, ?, ?)
+					 ON CONFLICT (group_id) DO UPDATE SET name = excluded.name, note = excluded.note`,
+	renameGroup: `UPDATE ${SHARE_GROUPS_TABLE} SET name = ? WHERE group_id = ?`,
+	deleteGroup: `DELETE FROM ${SHARE_GROUPS_TABLE} WHERE group_id = ?`,
+	listGroups: `SELECT * FROM ${SHARE_GROUPS_TABLE} ORDER BY name`,
+	insertMember: `INSERT INTO ${SHARE_GROUP_MEMBERS_TABLE} (group_id, subject_id, added_by, added_at)
+					 VALUES (?, ?, ?, ?) ON CONFLICT (group_id, subject_id) DO NOTHING`,
+	deleteMember: `DELETE FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? AND subject_id = ?`,
+	listMembers: `SELECT * FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE group_id = ? ORDER BY subject_id`,
+	groupIdsFor: `SELECT group_id FROM ${SHARE_GROUP_MEMBERS_TABLE} WHERE subject_id = ? ORDER BY group_id`,
+
+	/** The trail, newest first, under a WHERE built by {@link eventsWhere}; binds its params then the limit. */
+	events: (where: string): string =>
+		`SELECT * FROM ${SHARE_EVENTS_TABLE} WHERE ${where} ORDER BY event_id DESC LIMIT ?`,
+
+	// ── The D1 store's atomic forms ────────────────────────────────────────────────────────
+	// D1 has no interactive transaction, so "read the grant, then decide what to log" cannot
+	// be two round trips without a window between them. These write the audit row FROM the
+	// grant row inside one `batch()`, so the decision and the write are one atomic step. They
+	// are listed here beside the sync forms they must agree with — `d1.spec.ts` runs both
+	// stores through one scenario and compares every table.
+
+	/**
+	 * The grant's event, read from the grant as it stands BEFORE the upsert that follows it in
+	 * the same batch: `regrade` (with the old level) when the level changes, `grant` otherwise.
+	 * Binds at, level, app, kind, resource_id, subject_type, subject_id, level, level, actor,
+	 * note, then the five {@link ONE_GRANT} keys.
+	 */
+	insertGrantEvent: `INSERT INTO ${SHARE_EVENTS_TABLE} ${EVENT_COLUMNS}
+			 SELECT ?, CASE WHEN g.level IS NOT NULL AND g.level <> ? THEN 'regrade' ELSE 'grant' END,
+			        ?, ?, ?, ?, ?, ?,
+			        CASE WHEN g.level <> ? THEN g.level ELSE NULL END, ?, ?
+			   FROM (SELECT 1) AS one
+			   LEFT JOIN ${SHARE_GRANTS_TABLE} AS g ON g.${ONE_GRANT.replaceAll(" AND ", " AND g.")}
+			 RETURNING *`,
+
+	/**
+	 * One `revoke` event per grant matching `where`, oldest grant first — written BEFORE the
+	 * delete that follows it in the same batch. Binds at, actor, note, then `where`'s params.
+	 */
+	insertRevokeEvents: (where: string): string => `INSERT INTO ${SHARE_EVENTS_TABLE} ${EVENT_COLUMNS}
+			 SELECT ?, 'revoke', app, kind, resource_id, subject_type, subject_id, level, NULL, ?, ?
+			   FROM ${SHARE_GRANTS_TABLE} WHERE ${where} ORDER BY grant_id
+			 RETURNING *`,
+	oneGrant: ONE_GRANT,
+	resourceGrants: RESOURCE_GRANTS,
+	subjectGrants: SUBJECT_GRANTS,
+	groupGrants: GROUP_GRANTS,
+} as const;
+
+/** The trail's WHERE and its params, bound to one app — the filter both stores apply. */
+export function eventsWhere(
+	app: string,
+	query: { kind?: string; id?: string; subject?: { type: string; id: string } },
+): { where: string; params: (string | number)[] } {
+	const clauses = ["app IS NULL OR app = ?"];
+	const params: (string | number)[] = [app];
+	if (query.kind !== undefined) {
+		clauses.push("kind = ?");
+		params.push(query.kind);
+	}
+	if (query.id !== undefined) {
+		clauses.push("resource_id = ?");
+		params.push(query.id);
+	}
+	if (query.subject) {
+		clauses.push("subject_type = ? AND subject_id = ?");
+		params.push(query.subject.type, query.subject.id);
+	}
+	return {
+		where: clauses.map((clause) => `(${clause})`).join(" AND "),
+		params,
+	};
+}
+
+/** Newest first, capped: default 200, never more than 1000, never less than 1. */
+export const eventLimit = (limit: number | undefined): number => Math.max(1, Math.min(limit ?? 200, 1000));