@pithy-sh/audit 0.1.0

package/src/http/schemas.ts

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import { AuditAction, AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
+import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
+import { z } from "zod";
+
+/**
+ * The request contracts audit's two routes declare (CLAUDE.md §HTTP).
+ *
+ * Every one of these is a **bound on something a caller chose**, which is the whole job here: a
+ * control-plane credential is verified, but verified is not trusted, and a management client with a
+ * bug can ask for a million rows off the largest table in the project as easily as a hostile one can.
+ *
+ * The free-text filters are bounded strings rather than enums, deliberately. `action` is a federated
+ * taxonomy — every capability declares its own codes and core holds no closed union — so the valid
+ * set is not knowable here, and the same is true of `resourceType`, `project`, and `worker`. Each is
+ * only ever compared, never interpreted, so a filter naming something this deployment has never
+ * recorded is an empty page rather than a 400. That is the better answer to the same question: a
+ * dashboard filtering by a capability the adopter removed should show nothing, not fail.
+ */
+
+/** How long any single filter value may be. Generous for a name, far short of a payload. */
+const MAX_FILTER_LENGTH = 256;
+
+/** A bounded free-text filter value — compared against a column, never interpreted. */
+const FilterValue = z.string().min(1).max(MAX_FILTER_LENGTH);
+
+/**
+ * The tenant filter, where **an empty value is the null filter**: `?tenant=acme` is one tenant's trail,
+ * `?tenant=` is the events that belong to no tenant, and omitting it entirely filters nothing.
+ *
+ * Three states over a query string that natively has two, so the third needs an encoding. The empty
+ * string is the one value that cannot collide: `FilterValue` is `min(1)`, so no tenant id is ever
+ * empty, and no adopter can be locked out of filtering for a tenant whose id happens to be the sentinel
+ * — which is what `?tenant=none` or `?tenant=null` would have risked. It is decoded here rather than in
+ * the handler, so `AuditQuery`'s `string | null` is what reaches the query builder.
+ */
+const TenantFilter = z.union([FilterValue, z.literal("").transform(() => null)]);
+
+/**
+ * An inclusive time bound, as ISO-8601, decoded to a `Date` by the schema rather than by the handler.
+ *
+ * The conversion belongs here because a handler takes typed values: the route signature carries the
+ * contract, so `from` reaches the query as the `Date` the filter wants and no handler ever parses a
+ * caller's string.
+ */
+const TimeBound = z
+  .string()
+  .datetime({ offset: true })
+  .transform((value) => new Date(value));
+
+/** One event's id in the path. */
+export const AuditEventIdParam = z
+  .object({
+    eventId: z
+      .string()
+      .uuid()
+      .describe(
+        "The event's `eventId` — the recorder's UUID idempotency key, not the internal autoincrement `id`. A param schema constrains the string; the handler still does the lookup.",
+      ),
+  })
+  .describe("The path parameters of the single-event route.");
+export type AuditEventIdParam = z.infer<typeof AuditEventIdParam>;
+
+/**
+ * The trail query: what to filter by, and where to resume.
+ *
+ * Field names match {@link AuditQuery} exactly, so the validated object is the filter — there is no
+ * hand-written mapping in the handler for a rename to fall out of sync with.
+ */
+export const ListAuditEventsQuery = z
+  .object({
+    actorType: AuditActorType.optional().describe(
+      "Filter to one kind of principal. `control-plane` is the one that separates a management client's own actions from the adopter's users'.",
+    ),
+    actorId: FilterValue.optional().describe("Filter to one principal — a user id, a service name, a token subject."),
+    action: AuditAction.max(MAX_FILTER_LENGTH)
+      .optional()
+      .describe("Filter to one exact `domain/reason` action code. Exact, never a prefix — the taxonomy is federated."),
+    outcome: AuditOutcome.optional().describe(
+      "Filter to one outcome. `denied` is the one worth watching: a run of denials is what a credential being probed looks like.",
+    ),
+    severity: AuditSeverity.optional().describe("Filter to one severity."),
+    resourceType: FilterValue.optional().describe("Filter to the kind of thing acted on (`user`, `secret`)."),
+    resourceId: FilterValue.optional().describe("Filter to one target — everything that happened to this thing."),
+    project: FilterValue.optional().describe("Filter to one project, as the recorder stamped it."),
+    environment: FilterValue.optional().describe("Filter to one environment (`dev` | `staging` | `prod`)."),
+    worker: FilterValue.optional().describe(
+      "Filter to one `apps/<name>` Worker. Two Workers sharing a database share this table, so this is the only column that tells their events apart.",
+    ),
+    tenant: TenantFilter.optional().describe(
+      "Filter to one tenant — whose actions these were, as the emitter recorded them. Send it empty (`?tenant=`) for the events that belong to no tenant: a CLI-originated action, a fleet-wide one, or a row recorded before the column existed. Omit it to filter nothing.",
+    ),
+    from: TimeBound.optional().describe("Inclusive lower bound on when the event occurred, ISO-8601."),
+    to: TimeBound.optional().describe("Inclusive upper bound on when the event occurred, ISO-8601."),
+    cursor: z
+      .string()
+      .max(512)
+      .optional()
+      .describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page."),
+    limit: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_PAGE_SIZE)
+      .optional()
+      .describe("How many events to return. Bounded, because a verified client can still have a bug."),
+  })
+  .describe("The audit trail query: what to filter the trail by, and where to resume reading it.");
+export type ListAuditEventsQuery = z.infer<typeof ListAuditEventsQuery>;

package/src/http/views.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { AuditEventRow } from "../data/auditEvent";
+import type { AuditEventDetailView, AuditEventView } from "./responses";
+
+/**
+ * What a management client is shown of an audit event — decided here, once, rather than by whichever
+ * columns a query happened to select.
+ *
+ * **No route returns a raw row.** The trail is the most sensitive table Pithy ships: it is the record
+ * of every security-relevant action across every capability, and it carries personal data the adopter
+ * collected from their own users. Handing a `SELECT *` to a client means every column the schema ever
+ * gains is disclosed by default, which is exactly backwards.
+ *
+ * ## What is deliberately absent from both views
+ *
+ * `id`, the autoincrement surrogate. Its own schema says internal, never exposed, and that is right:
+ * it is monotonic, so publishing it tells a client how many events the project has recorded and lets
+ * it address rows by counting. Events are addressed by `eventId`, a UUID. The keyset cursor does
+ * carry `id` as a position, and that is a different thing — it is opaque, it is not a field a client
+ * can filter or address by, and it names only the row that client was just handed.
+ *
+ * ## What is in the detail view only, and why
+ *
+ * `ip`, `userAgent`, and `metadata`. These are the trail's personal data, and they are the reason
+ * {@link AUDIT_EVENT_DETAIL_READ_SCOPE} exists as a separate grant.
+ *
+ * - **`ip`** is a personal identifier under GDPR, and it is also the field a forensic read genuinely
+ *   needs — "was this login from where this person usually is". So it is exposed, not dropped;
+ *   dropping it would make the column pointless and the incident unanswerable. It is exposed one
+ *   event at a time, behind its own scope, so reading it is a decision rather than a side effect of
+ *   opening a dashboard.
+ * - **`userAgent`** is a device fingerprint. Same reasoning, same place.
+ * - **`metadata`** is a capability-specific bag whose contents nothing here can predict. `@pithy-sh/testers`
+ *   writes an invited tester's email address into it, on purpose, and other capabilities write resource
+ *   names and denial reasons. A page of a hundred events would therefore leak an arbitrary amount of
+ *   whatever every capability decided to record — so it is not in the listing at any page size.
+ *
+ * `sessionId` **is** in the list view, and it is not the exception it looks like. Better Auth's session
+ * row id is not its session token: the credential is `session.token`, which the trail never holds. The
+ * id is a correlation key, and correlating a chain of actions to one sign-in is most of what an audit
+ * trail is read for.
+ */
+
+/**
+ * ## The field list lives in `responses.ts`
+ *
+ * Both view types are `z.output` of the Zod objects there, so there is one declaration of what a
+ * client receives rather than an interface here and a mirror of it in every management client. A
+ * field added to one and not the other does not compile.
+ *
+ * Project one row for the listing.
+ */
+export function auditEventView(row: AuditEventRow): AuditEventView {
+  return {
+    eventId: row.eventId,
+    occurredAt: row.occurredAt.toISOString(),
+    action: row.action,
+    outcome: row.outcome,
+    severity: row.severity,
+    actorType: row.actorType,
+    actorId: row.actorId,
+    sessionId: row.sessionId,
+    resourceType: row.resourceType,
+    resourceId: row.resourceId,
+    requestId: row.requestId,
+    project: row.project,
+    environment: row.environment,
+    worker: row.worker,
+    // The point of the column: it turns "this was revoked, by this subject" into "…against this exact
+    // build". A forensic view that omitted it would leave the reader guessing which code ran.
+    version: row.version,
+    // In the listing, not gated behind the detail scope. It is an opaque id the adopter already holds,
+    // not personal data — and a client that can filter by tenant but cannot see which tenant a row
+    // carries has to take the filter on trust, which is how a row ends up drawn under the wrong heading.
+    tenant: row.tenant,
+  };
+}
+
+/** Project one row for the single-event read, network identifiers and metadata included. */
+export function auditEventDetailView(row: AuditEventRow): AuditEventDetailView {
+  return { ...auditEventView(row), ip: row.ip, userAgent: row.userAgent, metadata: row.metadata };
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+/**
+ * The package entrypoint — the surface `pithy add audit` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, the recorder/query seams an app reads the trail with, the federated
+ * action-constant helper, and the CLI emitter + actor resolver. Every other module is imported by
+ * deep path (`@pithy-sh/audit/src/...`); this is the documented contract, not a barrel.
+ */
+
+export { AuditTrailActions, defineAuditActions } from "./actions";
+export { type AuditCapability, type AuditConfigInput, audit, isAuditCapability } from "./capability";
+export { type CliAuditEvent, emitFromCLI } from "./cli/emitFromCLI";
+export {
+  type CfAccountTokenActorSource,
+  type CfActorSource,
+  type CfUserActorSource,
+  createCachedActorResolver,
+  type ResolvedActor,
+  resolveActor,
+} from "./cli/resolveActor";
+export { AuditEventRow } from "./data/auditEvent";
+export { type AuditDatabase, auditDatabase } from "./data/tables";
+export {
+  AUDIT_CONTROL_PLANE_SCOPES,
+  AUDIT_EVENT_DETAIL_READ_SCOPE,
+  AUDIT_TRAIL_READ_SCOPE,
+  auditAdminRoutes,
+} from "./http/guards";
+export { type AuditEventPage, type AuditQuery, pageAuditEvents, queryAuditEvents, readAuditEvent } from "./query";
+export { type AuditRecorderOptions, createAuditEmit, recordAuditEvent } from "./recorder";

package/src/migrations/0001_init.ts

@@ -0,0 +1,117 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { Kysely } from "kysely";
+import type { Migration } from "kysely/migration";
+
+/**
+ * Create the `pithy_audit_events` table in the configured audit database (the `DB` binding by
+ * default). The `pithy_audit_` prefix keeps it from clashing with an adopter's own tables.
+ *
+ * Identifiers are declared in **camelCase**: the runner installs `CamelCasePlugin`, which snake-cases
+ * every identifier in the emitted DDL (CLAUDE.md §Data layer). `pithyAuditEvents` becomes the SQL
+ * table `pithy_audit_events`; the column names match the Zod schema.
+ *
+ * The indexes serve the query shapes the trail is read by — time range (`occurredAt`), per-action
+ * (`action`), per-actor (`actorType`, `actorId`), per-resource (`resourceType`, `resourceId`), and
+ * per-tenant over a window (`tenant`, `occurredAt`).
+ * `down` is the tested inverse: drop the indexes, then the table (D1 has no transactional DDL).
+ *
+ * This is the whole audit schema, in one migration — see `CONTRIBUTING.md` §Migrations for why that is
+ * the shape while nothing is published, and what changes the day something is.
+ */
+export const audit_0001_init: Migration = {
+  up: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema
+      .createTable("pithyAuditEvents")
+      .addColumn("id", "integer", (c) => c.primaryKey().autoIncrement())
+      .addColumn("eventId", "text", (c) => c.notNull())
+      .addColumn("occurredAt", "integer", (c) => c.notNull())
+      .addColumn("action", "text", (c) => c.notNull())
+      .addColumn("outcome", "text", (c) => c.notNull())
+      .addColumn("severity", "text", (c) => c.notNull().defaultTo("info"))
+      .addColumn("actorType", "text", (c) => c.notNull())
+      .addColumn("actorId", "text")
+      .addColumn("sessionId", "text")
+      .addColumn("resourceType", "text")
+      .addColumn("resourceId", "text")
+      .addColumn("ip", "text")
+      .addColumn("userAgent", "text")
+      .addColumn("requestId", "text")
+      .addColumn("metadata", "text")
+      // Where the event was recorded, stamped by the recorder from the Worker's own vars — never by an
+      // emitter. Nullable, and permanently so: a Worker scaffolded without the vars carries none of
+      // them, and a CLI-originated action came from no Worker at all. `null` means "not recorded",
+      // which is a true statement; a default would invent an origin and make the invention unqueryable.
+      // `version` joins them for the same reason and on the same terms: the Cloudflare build id the
+      // recorder read from `CF_VERSION_METADATA`. It is what turns "this was revoked" into "this was
+      // revoked, by this subject, against this exact build". Null for a CLI action, and for a Worker
+      // that does not declare the binding.
+      .addColumn("project", "text")
+      .addColumn("environment", "text")
+      .addColumn("worker", "text")
+      .addColumn("version", "text")
+      // Whose action it was. The four columns above say which deployment of *ours* wrote a row; in a
+      // multi-tenant application all four are constant across every row, so nothing on the event
+      // distinguished one customer's history from another's. `actorId` does not either: one person can
+      // administer two tenants, and every event they produce carries the same actor.
+      //
+      // Nullable, with no default, permanently — for the same reason the origin columns are. A
+      // single-tenant app has no such dimension and must not be made to invent one; a CLI-originated
+      // action and a fleet-wide operator action genuinely have no tenant. `null` means "not
+      // tenant-scoped", which is a true statement. The tenant of an action is a fact at the time of the
+      // action; a membership table only knows who belongs where *now*, so deriving one from the other
+      // would hand a year of one tenant's history to another the day somebody changes teams.
+      .addColumn("tenant", "text")
+      .execute();
+
+    // Unique on eventId — the recorder's idempotency key. A retried write reuses the same eventId, so
+    // this index turns a post-commit retry into a UNIQUE violation the retry wrapper treats as "already
+    // landed" rather than a duplicate row.
+    await db.schema
+      .createIndex("pithyAuditEventsEventIdIdx")
+      .on("pithyAuditEvents")
+      .column("eventId")
+      .unique()
+      .execute();
+    await db.schema.createIndex("pithyAuditEventsOccurredAtIdx").on("pithyAuditEvents").column("occurredAt").execute();
+    await db.schema.createIndex("pithyAuditEventsActionIdx").on("pithyAuditEvents").column("action").execute();
+    await db.schema
+      .createIndex("pithyAuditEventsActorIdx")
+      .on("pithyAuditEvents")
+      .columns(["actorType", "actorId"])
+      .execute();
+    await db.schema
+      .createIndex("pithyAuditEventsResourceIdx")
+      .on("pithyAuditEvents")
+      .columns(["resourceType", "resourceId"])
+      .execute();
+    // One composite index in the order a reader narrows by: a project owns environments, an environment
+    // holds Workers. SQLite uses a leading subset of a composite index, so this also serves `project`
+    // alone and `project + environment` without a second index. A `worker`-only filter is not a shape
+    // the trail is read by — a Worker name only means anything inside its project.
+    await db.schema
+      .createIndex("pithyAuditEventsOriginIdx")
+      .on("pithyAuditEvents")
+      .columns(["project", "environment", "worker"])
+      .execute();
+    // The tenant read is (tenant, time): one tenant's trail, newest first, usually over a window. So the
+    // index leads with `tenant` and carries `occurredAt` — a `tenant`-only index would still leave the
+    // sort to a scan of the largest table in most projects.
+    await db.schema
+      .createIndex("pithyAuditEventsTenantIdx")
+      .on("pithyAuditEvents")
+      .columns(["tenant", "occurredAt"])
+      .execute();
+  },
+  down: async (db: Kysely<unknown>): Promise<void> => {
+    await db.schema.dropIndex("pithyAuditEventsTenantIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsOriginIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsResourceIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsActorIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsActionIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsOccurredAtIdx").execute();
+    await db.schema.dropIndex("pithyAuditEventsEventIdIdx").execute();
+    await db.schema.dropTable("pithyAuditEvents").execute();
+  },
+};

package/src/query.ts

@@ -0,0 +1,197 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: FSL-1.1-MIT
+
+import type { AuditActorType, AuditOutcome, AuditSeverity } from "@pithy-sh/core/src/audit/auditEvent";
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
+import { AuditEventRow } from "./data/auditEvent";
+import type { AuditDatabase } from "./data/tables";
+
+/**
+ * A filter over the audit trail. Every field is optional and ANDed together; an empty filter returns
+ * the whole trail (newest first). This is the typed read seam consumers use to read events by actor,
+ * action, time range, resource, outcome, severity, origin, and tenant.
+ *
+ * `tenant` is the only field where `null` is a value rather than an absence — see its own doc. Every
+ * other field is "match this or don't filter".
+ *
+ * It is a Kysely query first: `src/http/routes.ts` is the control-plane surface over it, and it is
+ * this package's own contribution behind `requireControlPlane(scope)` rather than something core
+ * reaches in and adds. `actorType: "control-plane"` is what separates a management client's actions
+ * from the adopter's own users', which is the question that surface is actually asked.
+ */
+export interface AuditQuery {
+  /** Match the acting principal's kind. */
+  actorType?: AuditActorType;
+  /** Match the acting principal's id. */
+  actorId?: string;
+  /** Match an exact `domain/reason` action code. */
+  action?: string;
+  /** Match the outcome (`success` | `failure` | `denied`). */
+  outcome?: AuditOutcome;
+  /** Match the severity (`info` | `warning` | `critical`). */
+  severity?: AuditSeverity;
+  /** Match the targeted resource's type. */
+  resourceType?: string;
+  /** Match the targeted resource's id. */
+  resourceId?: string;
+  /** Match the project the event was recorded in. */
+  project?: string;
+  /** Match the environment the recording Worker served. */
+  environment?: string;
+  /** Match the recording Worker's `apps/<name>` directory name. */
+  worker?: string;
+  /**
+   * Match the tenant the action was taken for — the read this column exists to serve, usually with a
+   * time range.
+   *
+   * **`null` is a filter, not an absence.** Omitted (`undefined`) means "do not filter by tenant";
+   * `null` means "the events that belong to no tenant" — a CLI-originated action, a fleet-wide operator
+   * action, a row recorded before the column existed. Both are questions an adopter genuinely asks, and
+   * the second one is why this is `string | null` rather than `string`: without it, asking it means
+   * writing SQL against this capability's own table.
+   */
+  tenant?: string | null;
+  /** Inclusive lower bound on `occurredAt`. */
+  from?: Date;
+  /** Inclusive upper bound on `occurredAt`. */
+  to?: Date;
+  /**
+   * Cap the number of rows returned. {@link queryAuditEvents} uses it verbatim; {@link pageAuditEvents}
+   * clamps it into `[1, MAX_PAGE_SIZE]`, because that one answers a caller over HTTP.
+   */
+  limit?: number;
+  /**
+   * Where to resume, from the previous page's `nextCursor`. Read only by {@link pageAuditEvents}, and
+   * opaque — a malformed one is a first page, never an error (see `@pithy-sh/core/src/data/cursor`).
+   */
+  cursor?: string;
+}
+
+/**
+ * One page of the trail, and where the next one starts.
+ *
+ * `nextCursor` is null at the end of the list, and knowing that costs no `COUNT` — the query
+ * over-fetches by one row and {@link toPage} drops it. On the largest table in most projects, a count
+ * query per page is the difference between a page load and a table scan.
+ */
+export interface AuditEventPage {
+  /** The page, newest first. */
+  events: AuditEventRow[];
+  /** Where the next page starts, or null at the end of the trail. */
+  nextCursor: string | null;
+}
+
+/**
+ * The filtered, ordered query both readers run — one builder, so a filter can never mean two things.
+ *
+ * The order is `(occurredAt desc, id desc)` and it is not an incidental choice: it is what the keyset
+ * cursor names a position in. `id` is the tiebreak, and without it two events recorded in the same
+ * millisecond straddle a page boundary and one of them is skipped or returned twice — which on an
+ * audit trail is a missing record, not a cosmetic glitch.
+ */
+function auditEventQuery(db: AuditDatabase, filter: AuditQuery) {
+  let query = db.selectFrom("pithyAuditEvents").selectAll();
+
+  if (filter.actorType !== undefined) query = query.where("actorType", "=", filter.actorType);
+  if (filter.actorId !== undefined) query = query.where("actorId", "=", filter.actorId);
+  if (filter.action !== undefined) query = query.where("action", "=", filter.action);
+  if (filter.outcome !== undefined) query = query.where("outcome", "=", filter.outcome);
+  if (filter.severity !== undefined) query = query.where("severity", "=", filter.severity);
+  if (filter.resourceType !== undefined) query = query.where("resourceType", "=", filter.resourceType);
+  if (filter.resourceId !== undefined) query = query.where("resourceId", "=", filter.resourceId);
+  // The origin filters, in the composite index's column order — `project`, then `environment`, then
+  // `worker` — so a narrowing query uses a leading subset of `pithyAuditEventsOriginIdx` rather than
+  // scanning. Note these match a *recorded* origin: a row written before the columns existed has NULL
+  // and is excluded by any of them, which is correct — it has no origin to match.
+  if (filter.project !== undefined) query = query.where("project", "=", filter.project);
+  if (filter.environment !== undefined) query = query.where("environment", "=", filter.environment);
+  if (filter.worker !== undefined) query = query.where("worker", "=", filter.worker);
+  // The tenant filter, and the one place `null` is a value rather than "unset". `= null` matches
+  // nothing in SQL, so a null filter has to become `is null` — which is also the reason this reads
+  // `!== undefined` rather than a truthiness check. Placed before the time bounds so it leads
+  // `pithyAuditEventsTenantIdx`, whose second column is `occurredAt`: one tenant's trail over a window
+  // is the query, and it must not scan the largest table in the project.
+  if (filter.tenant !== undefined) {
+    query = filter.tenant === null ? query.where("tenant", "is", null) : query.where("tenant", "=", filter.tenant);
+  }
+  if (filter.from !== undefined) query = query.where("occurredAt", ">=", SQLiteDate.encode(filter.from));
+  if (filter.to !== undefined) query = query.where("occurredAt", "<=", SQLiteDate.encode(filter.to));
+
+  return query.orderBy("occurredAt", "desc").orderBy("id", "desc");
+}
+
+/**
+ * A decoded cursor, narrowed to the position this table's ordering can actually use.
+ *
+ * `occurredAt` is a **ms-epoch number** here, not an ISO string — Pithy's own tables store dates as
+ * numbers, and only Better Auth's store them as TEXT. A cursor carrying a string would compare
+ * lexically against an integer column and silently return the wrong page, so anything that is not a
+ * pair of numbers is treated as no cursor at all. A bad cursor is a first page, which is the same
+ * answer `decodeCursor` gives to a truncated or stale one.
+ */
+function keysetPosition(cursor: PageCursor | undefined): { sort: number; id: number } | undefined {
+  if (!cursor) return undefined;
+  if (typeof cursor.sort !== "number" || typeof cursor.id !== "number") return undefined;
+  return { sort: cursor.sort, id: cursor.id };
+}
+
+/**
+ * Read audit events matching `filter`, newest first (`occurredAt` then `id`, both descending). Each
+ * row is decoded back through {@link AuditEventRow} — dates become `Date`s, `metadata` a parsed and
+ * validated object — so callers get the app shape, never raw SQLite columns.
+ */
+export async function queryAuditEvents(db: AuditDatabase, filter: AuditQuery = {}): Promise<AuditEventRow[]> {
+  let query = auditEventQuery(db, filter);
+  if (filter.limit !== undefined) query = query.limit(filter.limit);
+  const rows = await query.execute();
+  return rows.map((row) => AuditEventRow.parse(row));
+}
+
+/**
+ * One page of the trail, resumable — the read the control-plane route serves.
+ *
+ * **Keyset, never offset.** The audit table is appended to constantly while somebody is reading it, so
+ * with `OFFSET` every event recorded during a read pushes one row from the page a client already has
+ * onto the page it is about to fetch: it sees that row twice, and any row that fell off the far end it
+ * never sees at all. On a security trail, "you may silently miss a record while paging" is not a
+ * usability defect. The cursor names the last row's exact position instead, so the next page starts
+ * where the previous ended whatever was written in between.
+ */
+export async function pageAuditEvents(db: AuditDatabase, filter: AuditQuery = {}): Promise<AuditEventPage> {
+  const limit = pageLimit(filter.limit);
+  const position = keysetPosition(decodeCursor(filter.cursor));
+
+  let query = auditEventQuery(db, filter);
+  if (position) {
+    // The descending-keyset predicate: strictly older, or the same instant and a lower surrogate id.
+    query = query.where((eb) =>
+      eb.or([
+        eb("occurredAt", "<", position.sort),
+        eb.and([eb("occurredAt", "=", position.sort), eb("id", "<", position.id)]),
+      ]),
+    );
+  }
+
+  // One more than asked for: the extra row is how "is there another page" is answered without a count.
+  const rows = await query.limit(limit + 1).execute();
+  // Decoded before the split, so the cursor is derived from the app shape rather than from whichever
+  // union the row type allows. `getTime()` is the ms-epoch the column actually stores — this table is
+  // Pithy's own, so its dates are numbers, not the ISO-8601 TEXT Better Auth's tables hold.
+  const decoded = rows.map((row) => AuditEventRow.parse(row));
+  const page = toPage(decoded, limit, (row) => ({ sort: row.occurredAt.getTime(), id: row.id }));
+  return { events: page.items, nextCursor: page.nextCursor };
+}
+
+/**
+ * Read one event by its `eventId`, or null when there is none.
+ *
+ * Addressed by `eventId` — the recorder's UUID idempotency key, uniquely indexed — and never by the
+ * autoincrement `id`. `id` is a surrogate that leaks how many events a project has recorded and is
+ * guessable by counting; `eventId` is neither, and it is the value the trail's own idempotency
+ * guarantee is written against.
+ */
+export async function readAuditEvent(db: AuditDatabase, eventId: string): Promise<AuditEventRow | null> {
+  const row = await db.selectFrom("pithyAuditEvents").selectAll().where("eventId", "=", eventId).executeTakeFirst();
+  return row ? AuditEventRow.parse(row) : null;
+}