From c72ea7630a5c1df6d58add5aec961c13c3af5f3e Mon Sep 17 00:00:00 2001
From: IHUOMA NKECHI BRIDGET <bridgetthnkechi87@gmail.com>
Date: Tue, 28 Jul 2026 19:57:07 +0100
Subject: [PATCH] Build scalable filterable audit log system

---
 apps/dashboard/app/activity/page.tsx        |  50 +++++--
 apps/dashboard/lib/activity/mapper.ts       |  13 +-
 apps/dashboard/test/activity-mapper.test.ts |  59 +++++++-
 apps/dashboard/test/activity-query.test.ts  |  24 ++++
 docs/audit-log-schema.md                    | 152 ++++++++++++++++++++
 5 files changed, 273 insertions(+), 25 deletions(-)
 create mode 100644 docs/audit-log-schema.md

diff --git a/apps/dashboard/app/activity/page.tsx b/apps/dashboard/app/activity/page.tsx
index c0e6e5f..43981f0 100644
--- a/apps/dashboard/app/activity/page.tsx
+++ b/apps/dashboard/app/activity/page.tsx
@@ -8,6 +8,7 @@ import { formatRelativeTime } from "@/lib/format-relative-time";
 import { useActivityFeed } from "@/lib/hooks/useActivityFeed";
 import { convertToCsv, downloadCsv, } from "@/lib/csv-export";
 import {
+  type ActivityEventEntity,
   type ActivityEventSeverity,
   type ActivityEventSource,
   type ActivityEventType,
@@ -83,6 +84,15 @@ const SEVERITY_FILTERS: { label: string; value: ActivityEventSeverity | "" }[] =
   { label: "Critical", value: "critical" },
 ];
 
+const ENTITY_TYPE_FILTERS: { label: string; value: ActivityEventEntity["type"] | "" }[] = [
+  { label: "All entity types", value: "" },
+  { label: "Pass", value: "pass" },
+  { label: "Guild", value: "guild" },
+  { label: "Member", value: "member" },
+  { label: "Verification", value: "verification" },
+  { label: "Webhook", value: "webhook" },
+];
+
 const SORT_OPTIONS: { label: string; value: ActivitySortOrder }[] = [
   { label: "Newest first", value: "newest" },
   { label: "Oldest first", value: "oldest" },
@@ -106,6 +116,7 @@ function ActivityPageContent() {
   const [type, setType] = useState<ActivityEventType | "">(() => (searchParams.get("type") as ActivityEventType | null) ?? "");
   const [source, setSource] = useState<ActivityEventSource | "">(() => (searchParams.get("source") as ActivityEventSource | null) ?? "");
   const [severity, setSeverity] = useState<ActivityEventSeverity | "">(() => (searchParams.get("severity") as ActivityEventSeverity | null) ?? "");
+  const [entityType, setEntityType] = useState<ActivityEventEntity["type"] | "">(() => (searchParams.get("entityType") as ActivityEventEntity["type"] | null) ?? "");
   const [actor, setActor] = useState(() => searchParams.get("actor") ?? "");
   const [from, setFrom] = useState(() => searchParams.get("from") ?? "");
   const [sort, setSort] = useState<ActivitySortOrder>(() => readSort(searchParams.get("sort")));
@@ -116,6 +127,7 @@ function ActivityPageContent() {
       type?: ActivityEventType | "";
       source?: ActivityEventSource | "";
       severity?: ActivityEventSeverity | "";
+      entityType?: ActivityEventEntity["type"] | "";
       actor?: string;
       from?: string;
       sort?: ActivitySortOrder;
@@ -134,6 +146,7 @@ function ActivityPageContent() {
       if (updates.type !== undefined) setOrDelete("type", updates.type);
       if (updates.source !== undefined) setOrDelete("source", updates.source);
       if (updates.severity !== undefined) setOrDelete("severity", updates.severity);
+      if (updates.entityType !== undefined) setOrDelete("entityType", updates.entityType);
       if (updates.actor !== undefined) setOrDelete("actor", updates.actor);
       if (updates.from !== undefined) setOrDelete("from", updates.from);
       if (updates.sort !== undefined) {
@@ -161,6 +174,7 @@ function ActivityPageContent() {
     const nextType = (searchParams.get("type") as ActivityEventType | null) ?? "";
     const nextSource = (searchParams.get("source") as ActivityEventSource | null) ?? "";
     const nextSeverity = (searchParams.get("severity") as ActivityEventSeverity | null) ?? "";
+    const nextEntityType = (searchParams.get("entityType") as ActivityEventEntity["type"] | null) ?? "";
     const nextActor = searchParams.get("actor") ?? "";
     const nextFrom = searchParams.get("from") ?? "";
     const nextSort = readSort(searchParams.get("sort"));
@@ -169,11 +183,12 @@ function ActivityPageContent() {
     if (nextType !== type) setType(nextType);
     if (nextSource !== source) setSource(nextSource);
     if (nextSeverity !== severity) setSeverity(nextSeverity);
+    if (nextEntityType !== entityType) setEntityType(nextEntityType);
     if (nextActor !== actor) setActor(nextActor);
     if (nextFrom !== from) setFrom(nextFrom);
     if (nextSort !== sort) setSort(nextSort);
     if (nextLimit !== limit) setLimit(nextLimit);
-  }, [actor, from, limit, searchParams, severity, sort, source, type]);
+  }, [actor, entityType, from, limit, searchParams, severity, sort, source, type]);
 
   const fromIso = useMemo(() => {
     if (!from) return undefined;
@@ -197,6 +212,7 @@ function ActivityPageContent() {
     type: type || undefined,
     source: source || undefined,
     severity: severity || undefined,
+    entityType: entityType || undefined,
     actor: actor.trim() || undefined,
     from: fromIso,
     sort,
@@ -250,17 +266,18 @@ function ActivityPageContent() {
   downloadCsv(csv, `activity-log-${date}.csv`);
 };
 
-  const hasActiveFilters = Boolean(type || source || severity || actor.trim() || from || sort !== "newest" || limit !== 10);
+  const hasActiveFilters = Boolean(type || source || severity || entityType || actor.trim() || from || sort !== "newest" || limit !== 10);
 
   const clearFilters = () => {
     setType("");
     setSource("");
     setSeverity("");
+    setEntityType("");
     setActor("");
     setFrom("");
     setSort("newest");
     setLimit(10);
-    updateActivityQuery({ type: "", source: "", severity: "", actor: "", from: "", sort: "newest", limit: 10 });
+    updateActivityQuery({ type: "", source: "", severity: "", entityType: "", actor: "", from: "", sort: "newest", limit: 10 });
   };
 
   return (
@@ -282,16 +299,6 @@ function ActivityPageContent() {
           className="inline-flex items-center gap-2 rounded-lg border border-slate-200 bg-white px-4 py-2 text-sm font-medium text-slate-600 shadow-sm transition-colors hover:border-slate-300 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-50"
           title="Fetch the latest activity events"
         >
-          </button>
-
-        <button
-          type="button"
-          onClick={refresh}
-          disabled={refreshing}
-          className="inline-flex items-center gap-2 rounded-lg border border-slate-200 bg-white px-4 py-2 text-sm font-medium text-slate-600 shadow-sm transition-colors hover:border-slate-300 hover:bg-slate-50 disabled:cursor-not-allowed disabled:opacity-50"
-          title="Fetch the latest activity events"
-          >
-
           <svg
             className={`h-4 w-4 ${refreshing ? "animate-spin" : ""}`}
             fill="none"
@@ -311,7 +318,7 @@ function ActivityPageContent() {
       </div>
 
       <div className="mb-4 rounded-xl border border-slate-200 bg-white p-4">
-        <div className="grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-7">
+        <div className="grid grid-cols-1 gap-3 md:grid-cols-2 xl:grid-cols-8">
           <label className="text-xs font-medium text-slate-600">
             Event type
             <select
@@ -357,6 +364,21 @@ function ActivityPageContent() {
             </select>
           </label>
 
+          <label className="text-xs font-medium text-slate-600">
+            Entity type
+            <select
+              value={entityType}
+              onChange={(event) => { const value = event.target.value as ActivityEventEntity["type"] | ""; setEntityType(value); updateActivityQuery({ entityType: value }); }}
+              className="mt-1 w-full rounded-lg border border-slate-200 bg-white px-3 py-2 text-sm text-slate-700 focus:border-primary-400 focus:outline-none focus:ring-2 focus:ring-primary-100"
+            >
+              {ENTITY_TYPE_FILTERS.map((option) => (
+                <option key={option.value || "all-entity-types"} value={option.value}>
+                  {option.label}
+                </option>
+              ))}
+            </select>
+          </label>
+
           <label className="text-xs font-medium text-slate-600">
             Actor
             <input
diff --git a/apps/dashboard/lib/activity/mapper.ts b/apps/dashboard/lib/activity/mapper.ts
index 4bc1b38..58ae83b 100644
--- a/apps/dashboard/lib/activity/mapper.ts
+++ b/apps/dashboard/lib/activity/mapper.ts
@@ -1,5 +1,6 @@
 import type { ActivityEvent, WebhookPayload } from "./types";
 import { CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION } from "@guildpass/integration-client";
+import { sanitiseWebhookData } from "./sanitise";
 
 function displayValue(...values: Array<unknown>): string {
   const value = values.find((item) => typeof item === "string" && item.length > 0);
@@ -34,7 +35,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           id: entityId(data.id, data.wallet, data.name),
           name: typeof data.name === "string" ? data.name : undefined,
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
     }
@@ -58,7 +59,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           id: entityId(data.id, data.wallet, data.name),
           name: typeof data.name === "string" ? data.name : undefined,
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
     }
@@ -81,7 +82,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           id: entityId(data.id, data.name),
           name: typeof data.name === "string" ? data.name : undefined,
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
     }
@@ -104,7 +105,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           id: entityId(data.id, data.name),
           name: typeof data.name === "string" ? data.name : undefined,
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
     }
@@ -127,7 +128,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           id: entityId(data.id, data.name),
           name: typeof data.name === "string" ? data.name : undefined,
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
     }
@@ -147,7 +148,7 @@ export function mapWebhookToActivity(payload: WebhookPayload): ActivityEvent | n
           type: "verification",
           id: entityId(data.wallet),
         },
-        metadata: data,
+        metadata: sanitiseWebhookData(type, data),
         schemaVersion: CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION,
       };
 
diff --git a/apps/dashboard/test/activity-mapper.test.ts b/apps/dashboard/test/activity-mapper.test.ts
index d5093d7..c7932e2 100644
--- a/apps/dashboard/test/activity-mapper.test.ts
+++ b/apps/dashboard/test/activity-mapper.test.ts
@@ -63,7 +63,7 @@ describe("mapWebhookToActivity", () => {
       id: "member_456",
       name: "Bob",
     });
-    assert.strictEqual(activity?.metadata, data);
+    assert.deepStrictEqual(activity?.metadata, data);
   });
 
   test("maps pass.created webhooks", () => {
@@ -82,7 +82,7 @@ describe("mapWebhookToActivity", () => {
       id: "pass_123",
       name: "Founders Pass",
     });
-    assert.strictEqual(activity?.metadata, data);
+    assert.deepStrictEqual(activity?.metadata, data);
   });
 
   test("maps pass.updated webhooks", () => {
@@ -100,7 +100,7 @@ describe("mapWebhookToActivity", () => {
       id: "pass_456",
       name: "VIP Pass",
     });
-    assert.strictEqual(activity?.metadata, data);
+    assert.deepStrictEqual(activity?.metadata, data);
   });
 
   test("maps guild.updated webhooks", () => {
@@ -118,7 +118,7 @@ describe("mapWebhookToActivity", () => {
       id: "guild_123",
       name: "Adamantine Guild",
     });
-    assert.strictEqual(activity?.metadata, data);
+    assert.deepStrictEqual(activity?.metadata, data);
   });
 
   test("maps verification.completed webhooks", () => {
@@ -135,7 +135,7 @@ describe("mapWebhookToActivity", () => {
       type: "verification",
       id: "0x987",
     });
-    assert.strictEqual(activity?.metadata, data);
+    assert.deepStrictEqual(activity?.metadata, data);
   });
 
   test("returns null for unsupported webhook event types", () => {
@@ -174,3 +174,52 @@ describe("mapWebhookToActivity", () => {
     assert.strictEqual(guild?.description, "Guild settings updated: guild_without_name");
   });
 });
+
+describe("mapWebhookToActivity metadata sanitisation", () => {
+  test("strips fields outside the per-type allowlist from stored metadata", () => {
+    const activity = mapWebhookToActivity(
+      payload({
+        id: "evt_membership_created_extra_fields",
+        type: "membership.created",
+        data: {
+          id: "member_123",
+          name: "Alice",
+          wallet: "0xabc",
+          email: "alice@example.com",
+          password: "hunter2",
+        },
+      })
+    );
+
+    assert.deepStrictEqual(activity?.metadata, {
+      id: "member_123",
+      name: "Alice",
+      wallet: "0xabc",
+    });
+    assert.strictEqual("email" in (activity?.metadata ?? {}), false);
+    assert.strictEqual("password" in (activity?.metadata ?? {}), false);
+  });
+
+  test("stores an empty metadata object for unrecognised data fields", () => {
+    const activity = mapWebhookToActivity(
+      payload({
+        id: "evt_pass_created_extra_fields",
+        type: "pass.created",
+        data: { id: "pass_123", name: "Founders Pass", internalNotes: "do not expose" },
+      })
+    );
+
+    assert.deepStrictEqual(activity?.metadata, { id: "pass_123", name: "Founders Pass" });
+    assert.strictEqual("internalNotes" in (activity?.metadata ?? {}), false);
+  });
+
+  test("never stores the raw webhook data object as metadata by reference", () => {
+    const data = { id: "guild_123", name: "Adamantine Guild", secret: "leaked" };
+    const activity = mapWebhookToActivity(
+      payload({ id: "evt_guild_updated_extra_fields", type: "guild.updated", data })
+    );
+
+    assert.notStrictEqual(activity?.metadata, data);
+    assert.strictEqual("secret" in (activity?.metadata ?? {}), false);
+  });
+});
diff --git a/apps/dashboard/test/activity-query.test.ts b/apps/dashboard/test/activity-query.test.ts
index 8467512..7a15f98 100644
--- a/apps/dashboard/test/activity-query.test.ts
+++ b/apps/dashboard/test/activity-query.test.ts
@@ -96,6 +96,16 @@ describe("activity query contract", () => {
     assert.equal(result.nextCursor, "evt_query_003");
   });
 
+  test("filters by entityType alone", () => {
+    const result = filterActivityEvents(events, { entityType: "verification", limit: 10 });
+
+    assert.deepEqual(
+      result.events.map((event) => event.id),
+      ["evt_query_003"]
+    );
+    assert.equal(result.nextCursor, null);
+  });
+
   test("returns an empty page for valid filters with no matches", () => {
     const result = filterActivityEvents(events, {
       type: "guild.deleted",
@@ -140,4 +150,18 @@ describe("activity query contract", () => {
       ["limit", "type", "sort", "from"]
     );
   });
+
+  test("rejects an invalid entityType parameter", () => {
+    const parsed = parseActivityQuery(
+      new URL("https://example.test/api/activity?entityType=not-real").searchParams
+    );
+
+    assert.equal(parsed.ok, false);
+    if (parsed.ok) return;
+
+    assert.deepEqual(
+      parsed.errors.map((error) => error.field),
+      ["entityType"]
+    );
+  });
 });
diff --git a/docs/audit-log-schema.md b/docs/audit-log-schema.md
new file mode 100644
index 0000000..db6f640
--- /dev/null
+++ b/docs/audit-log-schema.md
@@ -0,0 +1,152 @@
+# Audit Log Schema & Filtering
+
+This document describes the structured audit event schema that backs the
+dashboard's `/activity` page, the filters and pagination model built on top
+of it, and the indexing strategy a future real datastore should adopt.
+
+There is a single audit event type in this codebase: `ActivityEvent`,
+defined in `packages/integration-client/src/types.ts` and re-exported
+through `apps/dashboard/lib/activity/types.ts`. It is shared by the
+dashboard, the webhook ingestion path, and is intended to be reused by a
+future webhook dispatch system — there is no separate "AuditEvent" type.
+
+## Schema
+
+```ts
+type ActivityEvent = {
+  id: string;
+  type: ActivityEventType;
+  source: ActivityEventSource;
+  severity: ActivityEventSeverity;
+  actor: { id?: string; name?: string; wallet?: string };
+  timestamp: string; // ISO 8601
+  description: string;
+  entity?: ActivityEventEntity;
+  metadata?: Record<string, any>;
+  changes?: ActivityChange[];
+  schemaVersion: number;
+};
+```
+
+| Field         | Description                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------- |
+| `id`          | Stable, unique event identifier (webhook payload id, or a generated id for dashboard mutations). |
+| `type`        | What happened — a closed union, see below.                                                       |
+| `source`      | Where the event originated: `dashboard`, `webhook`, `core_api`, or `reconciliation`.             |
+| `severity`    | `info`, `warning`, `error`, or `critical`.                                                       |
+| `actor`       | Who did it. All fields optional — a webhook may only know a wallet, a system action may know neither. |
+| `timestamp`   | ISO 8601 timestamp of when the event occurred.                                                   |
+| `description` | Human-readable summary shown in the UI.                                                          |
+| `entity`      | The object the event is about: `{ type: "pass" \| "guild" \| "member" \| "verification" \| "webhook", id, name? }`. |
+| `metadata`    | Free-form, event-type-specific data. For webhook-sourced events this is built via an explicit per-type field allowlist (`lib/activity/sanitise.ts`) — arbitrary webhook payload fields are never stored verbatim. |
+| `changes`     | Field-level before/after diff for mutation events (see `lib/activity/diff.ts`). Fields in `SENSITIVE_AUDIT_FIELDS` (`apiKey`, `password`, `token`, etc.) are unconditionally excluded from diffs. |
+| `schemaVersion` | Explicit schema version for backward-compatible reads (see below). |
+
+`ActivityEventType` is a closed union of 15 values covering pass, guild,
+member, access, settings, verification, and webhook lifecycle events (see
+`packages/integration-client/src/types.ts` for the full list).
+
+### Tenant scoping
+
+`ActivityEvent` has no first-class `guildId` field. Guild scope is derived
+by `activityEventGuildId()` in `apps/dashboard/lib/data/guild-scoped.ts`,
+which prefers `metadata.guildId` and falls back to `entity.id` when
+`entity.type === "guild"`. `filterActivityEventsByGuild()` applies this scope
+*before* the filters described below run, and events with no derivable guild
+are excluded once a tenant is selected — unscoped data is never leaked into
+a guild-scoped feed. See [Migration notes](#migration-notes-for-a-future-datastore)
+for why a real datastore should promote this to a column.
+
+### Schema versioning
+
+`CURRENT_ACTIVITY_EVENT_SCHEMA_VERSION` (currently `2`) is stamped on every
+event. `packages/integration-client/src/activity-event-migration.ts` holds an
+ordered chain of migrations keyed by source version; `upcastActivityEvent()`
+walks a raw stored event through that chain until it matches the current
+shape. Events written before `schemaVersion` existed are treated as V1.
+Adding a field means: bump the constant, add a `MIGRATIONS.set(n, ...)`
+entry, and add a fixture at the old version to the migration test suite.
+
+## Supported filters
+
+Filtering and validation live in `apps/dashboard/lib/activity/query.ts`.
+
+| Filter       | Query param  | Behavior                                                                 |
+| ------------ | ------------ | ------------------------------------------------------------------------- |
+| Event type   | `type`       | Exact match against `ActivityEventType`.                                  |
+| Source       | `source`     | Exact match against `ActivityEventSource`.                                |
+| Severity     | `severity`   | Exact match against `ActivityEventSeverity`.                              |
+| Entity type  | `entityType` | Exact match against `entity.type`.                                       |
+| Actor        | `actor`      | Case-insensitive substring match against `actor.id`, `actor.name`, and `actor.wallet`. |
+| Date range   | `from`       | Lower bound (inclusive) on `timestamp`, parsed as an ISO timestamp. There is currently no upper-bound (`to`) parameter — add one the same way if a bounded range becomes a requirement. |
+| Sort order   | `sort`       | `newest` (default) or `oldest`, by `timestamp` then `id` as a tiebreaker. |
+
+Filters combine with AND semantics — e.g. `type=member.joined&source=dashboard&entityType=member`
+returns only events matching all three. `parseActivityQuery()` validates raw
+`URLSearchParams` and returns field-specific errors (`{ field, message }[]`)
+for unknown enum values or malformed timestamps, surfaced by
+`GET /api/activity` as a `400 VALIDATION_ERROR` response.
+
+Guild scope (`guildId`) is applied separately, via a request header
+(`GUILD_ID_HEADER`) rather than a query parameter — see
+[Tenant scoping](#tenant-scoping).
+
+## Pagination
+
+Pagination is cursor-based, implemented by `filterActivityEvents()`:
+
+1. All matching events are filtered and sorted first.
+2. `limit` bounds the page size (default 20, max 100 — see `DEFAULT_ACTIVITY_LIMIT` / `MAX_ACTIVITY_LIMIT`).
+3. `cursor` is the `id` of the last event from the previous page. The next
+   page starts immediately after that event's position in the sorted list.
+4. The response includes `nextCursor` (the last event id in the current
+   page, or `null` when there are no more results) and `total` (the count of
+   all events matching the filters, independent of `limit`).
+
+This is intentionally structured as if it were already backed by a real,
+indexed query — the in-memory implementation is a stand-in for the query
+shape, not the target architecture.
+
+## Migration notes for a future datastore
+
+The current storage layer (`apps/dashboard/lib/activity/storage.ts`) has
+three interchangeable implementations behind `IActivityStorage`
+(`InMemoryActivityStorage`, `FileActivityStorage`,
+`DurableActivityStorage` for Postgres), selected via
+`ACTIVITY_STORAGE_MODE`. All three funnel through the same
+`filterActivityEvents()` function, so query semantics don't change when the
+backing store does.
+
+Moving to a real, high-volume datastore should change two things:
+
+1. **Promote `guildId` to a first-class column.** It currently lives inside
+   `metadata` by convention (see [Tenant scoping](#tenant-scoping)), which is
+   fine for an in-memory array scan but unindexable as a JSON blob at scale.
+2. **Replace id-position cursors with keyset pagination.** The in-memory
+   cursor works by finding `cursor`'s array index in the already-sorted list.
+   A real query should instead do:
+   ```sql
+   WHERE (timestamp, id) < (:cursor_timestamp, :cursor_id)  -- for "newest first"
+   ORDER BY timestamp DESC, id DESC
+   LIMIT :limit
+   ```
+   which means the opaque `cursor` string should encode both `timestamp` and
+   `id`, not just `id`.
+
+Recommended composite indexes, based on the filters above:
+
+| Index                                | Supports                                                        |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| `(guildId, timestamp)`                | The default guild-scoped, newest/oldest-first feed (the common case). |
+| `(actor, timestamp)`                  | Actor substring/exact-match filtering combined with date range.  |
+| `(entityType, entityId, timestamp)`   | "Show me the history of this pass/member/guild" drill-downs.     |
+
+`type`, `source`, and `severity` are low-cardinality enums best served as
+secondary filters within one of the above indexes (or a partial index) rather
+than indexed independently.
+
+`DurableActivityStorage.queryEvents()` currently reads the full
+`activity_events` table into memory and filters in application code
+(`getEvents()` then `filterActivityEvents()`); once volume justifies it, this
+should push the filters, sort, and `LIMIT`/keyset pagination down into SQL
+using the indexes above instead.