cursedbelt-server 4.26.1 → 4.28.0

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

@@ -0,0 +1,70 @@
+/**
+ * `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 { D1LikeDatabase } from "../d1/types.js";
+import { type ActivityFacets, type ActivityPage, type ActivityQuery, type ActivitySource } 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 declare function createD1ActivityLog(options: D1ActivityLogOptions): AsyncActivityLog;

package/dist/server/activity/d1.js

@@ -0,0 +1,68 @@
+import { ACTIVITY_SQL, buildStream, facetLimit, MAX_FACET, pageLimit, prepareRecord, toStreamEvent, } from "./query.js";
+export { ACTIVITY_DDL, ACTIVITY_EVENTS_TABLE } from "./schema.js";
+export { shareEventsSource } from "./shareSource.js";
+/** The activity log over D1. Runs no DDL — see the header. */
+export function createD1ActivityLog(options) {
+    const { db, app } = options;
+    const now = options.now ?? (() => new Date().toISOString());
+    const registered = options.sources ?? [];
+    const liveSources = async () => {
+        const live = [];
+        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) => buildStream(query, await liveSources());
+    return {
+        app,
+        async record(input) {
+            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 = {}) {
+            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();
+            const truncated = rows.length > limit;
+            return { events: rows.slice(0, limit).map(toStreamEvent), limit, truncated };
+        },
+        async count(query = {}) {
+            const { sql, params } = await stream(query);
+            const row = await db
+                .prepare(ACTIVITY_SQL.count(sql))
+                .bind(...params)
+                .first();
+            return row?.n ?? 0;
+        },
+        async facets(query = {}, limit = MAX_FACET) {
+            const { sql, params } = await stream(query);
+            const capped = facetLimit(limit);
+            const dimension = async (column) => (await db
+                .prepare(ACTIVITY_SQL.facet(sql, column))
+                .bind(...params, capped)
+                .all()).results.map((row) => ({ value: row.value, count: row.count }));
+            return {
+                actions: await dimension("action"),
+                actors: await dimension("actor"),
+                kinds: await dimension("kind"),
+            };
+        },
+        async sources() {
+            return ["log", ...(await liveSources()).map((source) => source.name)];
+        },
+    };
+}

package/dist/server/activity/migrations.d.ts

@@ -1,7 +1,5 @@
 import type { Migration } from "../migration/types.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 declare const ACTIVITY_EVENTS_TABLE = "activity_events";
+export { ACTIVITY_DDL, ACTIVITY_EVENTS_TABLE } from "./schema.js";
 /**
  * ONE append-only table per app, not a shadow table per business table.
  *

package/dist/server/activity/migrations.js

@@ -1,6 +1,8 @@
-/** 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";
+import { ACTIVITY_DDL } from "./schema.js";
+// 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.
  *
@@ -21,35 +23,8 @@ export const ACTIVITY_MIGRATIONS = [
     {
         name: "0001_activity_events",
         up(db) {
-            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);
         },
     },
 ];

package/dist/server/activity/query.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 } from "cursedbelt-core/activity/model";
+/**
+ * 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;
+}
+export declare const MAX_FACET = 25;
+export declare const toStreamEvent: (row: StreamRow) => ActivityEvent;
+export declare const ACTIVITY_SQL: {
+    /** Binds at, app, actor, action, kind, resource_id, outcome, note, data. */
+    readonly insert: "INSERT INTO activity_events\n\t\t   (at, app, actor, action, kind, resource_id, outcome, note, data)\n\t\t VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)";
+    readonly tableExists: "SELECT 1 AS ok FROM sqlite_master WHERE type = 'table' AND name = ?";
+    readonly ownSelect: "SELECT 'log' AS source, event_id AS seq, at, app, actor, action,\n\t                           kind, resource_id, outcome, note, data\n\t                      FROM activity_events";
+    /** 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`. */
+    readonly page: (stream: string) => string;
+    readonly count: (stream: string) => string;
+    /** Binds the stream's params, then the facet cap. `column` is one of three literals. */
+    readonly facet: (stream: string, column: "action" | "actor" | "kind") => string;
+};
+/** The limit a page actually applies: default 100, never above 1000 or below 1. */
+export declare const pageLimit: (limit: number | undefined) => number;
+/** The facet cap: default {@link MAX_FACET}, never above it or below 1. */
+export declare const facetLimit: (limit: number) => number;
+/**
+ * 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 declare function buildStream(query: ActivityQuery, liveSources: readonly ActivitySource[]): {
+    sql: string;
+    params: ActivityBindable[];
+};
+/**
+ * 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 declare 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">;
+};

package/dist/server/activity/query.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { isActivityAction, isActivityOutcome, } from "cursedbelt-core/activity/model";
+import { ACTIVITY_EVENTS_TABLE } from "./schema.js";
+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) => `%${value.replace(/[\\%_]/g, (ch) => `\\${ch}`)}%`;
+export const toStreamEvent = (row) => ({
+    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) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { 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) => `${stream} ORDER BY at DESC, seq DESC LIMIT ?`,
+    count: (stream) => `SELECT COUNT(*) AS n FROM (${stream})`,
+    /** Binds the stream's params, then the facet cap. `column` is one of three literals. */
+    facet: (stream, column) => `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 ?`,
+};
+/** The limit a page actually applies: default 100, never above 1000 or below 1. */
+export const pageLimit = (limit) => 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) => 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, liveSources) {
+    const params = [];
+    const selects = [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 = [];
+    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, input, now) {
+    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/dist/server/activity/schema.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare const ACTIVITY_EVENTS_TABLE = "activity_events";
+/** Every statement of the `0001_activity_events` migration, in order. Idempotent. */
+export declare const ACTIVITY_DDL: readonly string[];

package/dist/server/activity/schema.js

@@ -0,0 +1,43 @@
+/**
+ * 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 = [
+    `
+				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/dist/server/activity/shareSource.d.ts

@@ -1,4 +1,4 @@
-import type { ActivitySource } from "./store.js";
+import type { ActivitySource } from "./query.js";
 export interface ShareEventsSourceOptions {
     /** The satellite this log speaks for — the same value passed to
      *  `createActivityLog`, used where a group event names no resource. */

package/dist/server/activity/shareSource.js

@@ -25,7 +25,7 @@
  * fleet-wide board merges on that column and an unlabeled row would be
  * unattributable.
  */
-import { SHARE_EVENTS_TABLE } from "../sharing/migrations.js";
+import { SHARE_EVENTS_TABLE } from "../sharing/schema.js";
 export function shareEventsSource(options) {
     const table = options.table ?? SHARE_EVENTS_TABLE;
     const name = options.name ?? "share";

package/dist/server/activity/store.d.ts

@@ -33,68 +33,10 @@
  *  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 } from "cursedbelt-core/activity/model";
-/**
- * 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 type { Database } from "bun:sqlite";
+import type { ActivityEvent, ActivityEventInput } from "cursedbelt-core/activity/model";
+import { type ActivityFacets, type ActivityPage, type ActivityQuery, type ActivitySource } from "./query.js";
+export type { ActivityBindable, ActivityFacet, ActivityFacets, ActivityPage, ActivityQuery, ActivitySource, } from "./query.js";
 export interface ActivityLogOptions {
     db: Database;
     /** The satellite this log speaks for. Fixed at construction, so a caller