@ultimat3/admin 22.15.0 → 24.0.0

package/src/admin.ts

@@ -2,21 +2,40 @@
 // each action off the entity it names, builds the nav, and returns the route table plus the
 // audit log and authz every surface then shares. Nothing here queries or renders; it wires.
 
+// For its side effect: the admin's stylesheets are claimed for the surface that serves them.
+import './stylesheet-scope';
+import { ANONYMOUS_ADMIN_ACTOR, requestActor } from './actor';
 import { type AuditLog, memoryAuditLog } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
+import { batchPlan } from './batch';
+import { adminBatchJob } from './batch-job';
+import { adminCatalogKeys } from './catalog-keys';
 import type { CrudCtx } from './crud';
 import { permissionsForOperation } from './crud';
-import { AdminActionDuplicateError, AdminPagePathInvalidError } from './errors';
+import { type AdminDescription, describeAdmin } from './describe';
+import {
+  AdminActionDuplicateError,
+  AdminFieldUnsupportedError,
+  AdminPagePathInvalidError,
+  AdminRepoUnboundError,
+} from './errors';
+import { JOB_PERMISSION_NOUN, JOBS_GROUP, JOBS_PATH, jobsAdmin } from './jobs/job-resources';
+import { registerAdminMount } from './mounts';
 import { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
 import { type AdminCustomPage, type AdminPageComponent, pageNavItems, pageRoutes } from './pages';
-import type { AdminOperation } from './permissions';
-import type { AdminAction, AdminEntity, AdminJobSummary, AdminRow } from './registry';
+import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
+import { declareAdminPermissions, roleAuthz } from './policy-bridge';
+import type { AdminAction, AdminDb, AdminEntity, AdminRepo, AdminRow } from './registry';
+import { relatedOf } from './related';
+import { adminRepoFor, adminTablesOf } from './repo-entity';
 import {
   type AdminResource,
   type AdminResourceOptions,
   adminResource,
   resourceFor,
 } from './resource';
+import { LOOKUP_SEGMENT } from './resource-list';
+import { mountAdminRoutes } from './route-config';
 import { type AdminBranding, adminBranding, type ThemeAttributes, themeAttributes } from './theme';
 
 /** The host app's auth hook: it owns sessions, the admin owns what a session may do. */
@@ -27,6 +46,8 @@ export interface AdminAuth {
 
 export type AdminView =
   | 'list'
+  /** A resource read as a TARGET: the picker every filter and input referencing it searches. */
+  | 'lookup'
   | 'detail'
   | 'create'
   | 'edit'
@@ -56,16 +77,27 @@ export interface AdminRoute {
 
 export interface DefineAdminInput {
   readonly entities: readonly AdminEntity[];
-  /** Per-entity overrides and repo binding, keyed by entity name. */
+  /**
+   * The app's `database()` handle, passed once. Every entity's rows are read and written through
+   * its own table there — tenancy, soft delete and sealing included — so an app writes no adapter.
+   * An entity the handle does not carry needs `resources.<entity>.repo`, or it is
+   * `X_ADMIN_REPO_UNBOUND` here, at declaration.
+   */
+  readonly db?: AdminDb;
+  /** Per-entity overrides, keyed by entity name. `repo` replaces the handle's table for one. */
   readonly resources?: Readonly<Record<string, AdminResourceOptions>>;
   /** Registered actions. Each is attached to `action.entity`, or the global toolbar. */
   readonly actions?: readonly AdminAction[];
-  readonly jobs?: readonly AdminJobSummary[];
   /** Screens the generator would never write. Declared here so they are not a second surface. */
   readonly pages?: readonly AdminCustomPage[];
   readonly nav?: NavOptions;
   readonly branding?: Partial<AdminBranding>;
-  readonly auth: AdminAuth;
+  /**
+   * Both halves default. `actor`: the one the HTTP pipeline resolved for this request. `authz`:
+   * the app's role map (`roleAuthz()`) — every permission is "does a role this actor holds grant
+   * it". Pass `policyAuthz({ policies })` when a rule reads the row or the tenant.
+   */
+  readonly auth?: Partial<AdminAuth>;
   readonly audit?: AuditLog;
   /** Mount point. Every route path is prefixed with it. */
   readonly basePath?: string;
@@ -78,7 +110,6 @@ export interface AdminApp {
   readonly resources: readonly AdminResource[];
   /** Actions with no entity: imports, backfills, anything app-wide. */
   readonly globalActions: readonly AdminAction[];
-  readonly jobs: readonly AdminJobSummary[];
   readonly nav: readonly NavGroup[];
   readonly routes: readonly AdminRoute[];
   readonly audit: AuditLog;
@@ -88,12 +119,29 @@ export interface AdminApp {
   /** Nav for one actor, with everything they cannot open removed. */
   navFor(ctx: CrudCtx): readonly NavGroup[];
   ctx(input: { readonly actor: AdminActor; readonly requestId: string }): CrudCtx;
+  /**
+   * The handle for the request in flight: `auth.actor(request)`, with anonymous as a real actor a
+   * decision refuses. What every mounted screen and every write is decided against.
+   */
+  requestCtx(request: Request): Promise<CrudCtx>;
+  /**
+   * This admin as plain data — resources with their filters, sorts, scopes and row scope, routes
+   * with their permissions. What the manifest records; JSON-safe and sorted.
+   */
+  describe(): AdminDescription;
+  /**
+   * Every catalog key this declaration derives, sorted and distinct — what the `i18n` step asks
+   * each of the app's catalogs for (`catalog-keys.ts`).
+   */
+  catalogKeys(): readonly string[];
 }
 
 const VIEW_OPERATION: Readonly<
   Record<Exclude<AdminView, 'jobs' | 'audit' | 'dashboard' | 'page'>, AdminOperation>
 > = {
   list: 'list',
+  // A lookup IS a list read of the target — same gate, same row scope, same audit entry.
+  lookup: 'list',
   detail: 'detail',
   create: 'create',
   edit: 'update',
@@ -114,11 +162,12 @@ function resourceRoutes(basePath: string, resource: AdminResource): readonly Adm
       view,
       entity: resource.name,
       titleKey: resource.titleKey,
-      permissions: permissionsForOperation(resource.name, op),
+      permissions: permissionsForOperation(resource.permission, op),
     });
   };
 
   add('list', base);
+  add('lookup', `${base}/${LOOKUP_SEGMENT}`);
   add('create', `${base}/new`);
   add('detail', `${base}/:id`);
   add('edit', `${base}/:id/edit`);
@@ -187,24 +236,112 @@ function assertUniqueActionNames(
   }
 }
 
+/**
+ * The repo one resource reads through: its own `repo:` override, else the entity's table in the
+ * app's handle. Neither is refused HERE — a resource with no repo mounts four routes that all fail
+ * on the first row they ask for, and nothing would say so until an operator opened one.
+ */
+function repoFor(
+  entity: AdminEntity,
+  override: AdminRepo<AdminRow> | undefined,
+  tables: ReadonlyMap<string, Parameters<typeof adminRepoFor>[1]>,
+): AdminRepo<AdminRow> {
+  if (override !== undefined) return override;
+  const table = tables.get(entity.$name);
+  if (table === undefined) {
+    throw new AdminRepoUnboundError({ entity: entity.$name, handles: [...tables.keys()].sort() });
+  }
+  return adminRepoFor(entity, table);
+}
+
+/**
+ * A batch action belongs to a resource — the batch bar is a list's — and a declared threshold is a
+ * count. An action with a threshold declares the one `admin.batch` job here, at declaration, so a
+ * process that loads this admin is a process that can run its queued chunks.
+ */
+function assertBatchActions(
+  resources: readonly AdminResource[],
+  declared: readonly AdminAction[],
+): void {
+  for (const action of declared) {
+    if (action.batch !== undefined && action.entity === undefined) {
+      // The closest shipped code is a field's, and its cause renders `<entity>.<field>:` — so the
+      // two halves name WHERE the option was written, never a column of an entity called "admin".
+      throw new AdminFieldUnsupportedError({
+        entity: 'defineAdmin',
+        field: `actions["${action.name}"].batch`,
+        cause:
+          "declares batch with no entity: the batch bar is a resource list's, and a global action belongs to none",
+        fix: `name the resource the batch runs over — { name: '${action.name}', entity: '<entity>', batch: true } — or drop batch`,
+      });
+    }
+  }
+  for (const action of [...resources.flatMap((resource) => resource.actions), ...declared]) {
+    if (action.matching !== undefined && action.batch === undefined) {
+      throw new AdminFieldUnsupportedError({
+        entity: 'defineAdmin',
+        field: `actions["${action.name}"].matching`,
+        cause:
+          'declares matching without batch: "all matching" is an option of the batch bar, and this action is not in it',
+        fix: `add batch: true to { name: '${action.name}', … }, or drop matching`,
+      });
+    }
+  }
+  for (const action of resources.flatMap((resource) => resource.actions)) {
+    if (batchPlan(action) !== null) adminBatchJob();
+  }
+}
+
+/** The overview's sidebar link, gated on the route's own pair so the link and the page agree. */
+const jobsOverviewNavItem = (): NavItem & { readonly group: string } => ({
+  key: 'jobs',
+  labelKey: 'admin.jobs.title',
+  href: JOBS_PATH,
+  entity: null,
+  permissions: permissionsForOperation(JOB_PERMISSION_NOUN, 'list'),
+  group: JOBS_GROUP,
+});
+
 /** Derive the whole admin from the registries. */
 export function defineAdmin(input: DefineAdminInput): AdminApp {
   const basePath = input.basePath ?? '/admin';
   const branding = adminBranding(input.branding ?? {});
   const audit = input.audit ?? memoryAuditLog();
-  const actions = input.actions ?? [];
-  const overrides = input.resources ?? {};
+  // The jobs dashboard is declared for every admin: four resources and their actions, each an
+  // ordinary declaration an app could have written — and an app's `resources:` entry for one of
+  // them (`x_jobs: { rows }`) overrides it as it would its own.
+  const jobs = jobsAdmin(basePath);
+  const actions = [...(input.actions ?? []), ...jobs.actions];
+  const overrides: Readonly<Record<string, AdminResourceOptions>> = {
+    ...jobs.resources,
+    ...Object.fromEntries(
+      Object.entries(input.resources ?? {}).map(([name, own]) => [
+        name,
+        { ...(Object.hasOwn(jobs.resources, name) ? jobs.resources[name] : {}), ...own },
+      ]),
+    ),
+  };
+  const tables = input.db === undefined ? new Map() : adminTablesOf(input.db);
+  const auth: AdminAuth = {
+    actor: input.auth?.actor ?? (() => requestActor().actor),
+    authz: input.auth?.authz ?? roleAuthz(),
+  };
 
-  const resources = input.entities.map((entity) => {
+  const resources = [...input.entities, ...jobs.entities].map((entity) => {
     const own = actions.filter((action) => action.entity === entity.$name);
-    const opts = overrides[entity.$name];
+    const opts = Object.hasOwn(overrides, entity.$name) ? overrides[entity.$name] : undefined;
     return adminResource<AdminRow>(entity, {
       ...(opts ?? {}),
+      repo: repoFor(entity, opts?.repo, tables),
       actions: [...(opts?.actions ?? []), ...own],
     });
   });
 
   assertUniqueActionNames(resources, actions);
+  // Refused where they are written, not on the first detail page: a `related` name that is not a
+  // `hasMany` of the entity, a batch threshold that is not a count.
+  for (const resource of resources) relatedOf(resources, resource);
+  assertBatchActions(resources, actions);
 
   const pages = input.pages ?? [];
   const navOptions = input.nav ?? {};
@@ -212,7 +349,7 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     ...(navOptions.extra ?? []),
     ...pageNavItems(pages),
   ];
-  const nav = adminNav(resources, { ...navOptions, extra });
+  const nav = adminNav(resources, { ...navOptions, extra: [...extra, jobsOverviewNavItem()] });
   assertUniqueResourcePaths(basePath, resources);
   const generated: AdminRoute[] = [
     {
@@ -230,11 +367,11 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
       permissions: permissionsForOperation('admin', 'search'),
     },
     {
-      path: `${basePath}/jobs`,
+      path: `${basePath}${JOBS_PATH}`,
       view: 'jobs',
       entity: null,
       titleKey: 'admin.jobs.title',
-      permissions: permissionsForOperation('job', 'list'),
+      permissions: permissionsForOperation(JOB_PERMISSION_NOUN, 'list'),
     },
     {
       path: `${basePath}/audit`,
@@ -256,26 +393,53 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     ),
   ];
 
-  return {
+  // Every permission a route or an action names is one the policy layer must be able to hear
+  // about, whichever authz decides it: `can()` refuses a name its registry lacks.
+  declareAdminPermissions([
+    ...routes.flatMap((route) => route.permissions),
+    ...resources.flatMap((resource) =>
+      ADMIN_OPERATIONS.flatMap((op) => permissionsForOperation(resource.permission, op)),
+    ),
+    ...[...resources.flatMap((resource) => resource.actions), ...actions].map(
+      (action) => action.permission,
+    ),
+  ]);
+
+  const ctx = ({ actor, requestId }: { actor: AdminActor; requestId: string }): CrudCtx => ({
+    actor,
+    requestId,
+    audit,
+    authz: auth.authz,
+  });
+
+  const app: AdminApp = {
     basePath,
     branding,
     theme: themeAttributes(branding),
     resources,
     globalActions: actions.filter((action) => action.entity === undefined),
-    jobs: input.jobs ?? [],
     nav,
     routes,
     audit,
-    authz: input.auth.authz,
-    auth: input.auth,
+    authz: auth.authz,
+    auth,
     resource(name: string): AdminResource {
       return resourceFor(resources, name);
     },
-    navFor(ctx: CrudCtx): readonly NavGroup[] {
-      return visibleNav(nav, resources, ctx);
+    navFor(crud: CrudCtx): readonly NavGroup[] {
+      return visibleNav(nav, resources, crud);
     },
-    ctx({ actor, requestId }): CrudCtx {
-      return { actor, requestId, audit, authz: input.auth.authz };
+    ctx,
+    async requestCtx(request: Request): Promise<CrudCtx> {
+      const actor = await auth.actor(request);
+      return ctx({ actor: actor ?? ANONYMOUS_ADMIN_ACTOR, requestId: requestActor().requestId });
     },
+    describe: () => describeAdmin(basePath, resources, routes, audit.kind),
+    catalogKeys: () => adminCatalogKeys(app),
   };
+  // In the framework's one route list, as what they are: mounted, each with its permissions.
+  mountAdminRoutes(basePath, routes);
+  // Declared is mountable: a host serves every admin in this registry under its base path.
+  registerAdminMount(app);
+  return app;
 }

package/src/audit-pg.ts

@@ -0,0 +1,207 @@
+// The durable audit log: one framework table, one insert per entry, read back by keyset. What
+// `defineAdmin({ audit: postgresAuditLog() })` names — the memory log is a ring that forgets at
+// every restart, and a row's history that ends at the last deploy is not a history.
+
+import { isUltimateError, uuid } from '@ultimat3/core';
+import { type DbClient, db, withTransaction } from '@ultimat3/db';
+import {
+  AUDIT_READ_OPERATIONS,
+  type AuditDraft,
+  type AuditEntry,
+  type AuditFieldDiff,
+  type AuditLog,
+  type AuditOutcome,
+  type AuditQuery,
+  type AuditSink,
+  auditEntry,
+  auditLimit,
+  isAllowedRead,
+} from './audit';
+import { ADMIN_AUDIT_TABLE } from './audit-schema';
+import { jsonText } from './json-text';
+
+const SUBJECT = 'postgresAuditLog';
+
+/** `recorded_at` is the database's clock and not a parameter: the gap to `at` is the audit lag. */
+export const SQL_ADMIN_AUDIT_INSERT = `
+insert into x_admin_audit (
+  id, at, request_id, actor_id, actor_roles, org_id,
+  operation, kind, entity, entity_id, permission, outcome, reason, diff
+) values (
+  $1::uuid, $2::timestamptz, $3, $4, $5::jsonb, $6,
+  $7, $8, $9, $10, $11, $12, $13, $14::jsonb
+)
+`;
+
+const COLUMNS =
+  'id, at, request_id, actor_id, actor_roles, org_id, operation, kind, entity, entity_id, permission, outcome, reason, diff';
+
+interface AuditRow {
+  readonly id: string;
+  readonly at: Date | string;
+  readonly request_id: string;
+  readonly actor_id: string;
+  readonly actor_roles: unknown;
+  readonly org_id: string | null;
+  readonly operation: string;
+  readonly kind: string;
+  readonly entity: string;
+  readonly entity_id: string | null;
+  readonly permission: string;
+  readonly outcome: string;
+  readonly reason: string;
+  readonly diff: unknown;
+}
+
+/** A `jsonb` column, whichever way the driver hands it back: parsed, or as its text. */
+const parsed = (value: unknown): unknown => {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+};
+
+const OUTCOMES: readonly AuditOutcome[] = ['allowed', 'denied', 'failed'];
+
+const entryOf = (row: AuditRow): AuditEntry => {
+  const roles = parsed(row.actor_roles);
+  const diff = parsed(row.diff);
+  const outcome = OUTCOMES.find((known) => known === row.outcome) ?? 'failed';
+  return {
+    id: row.id,
+    at: (row.at instanceof Date ? row.at : new Date(row.at)).toISOString(),
+    requestId: row.request_id,
+    actor: {
+      id: row.actor_id,
+      roles: Array.isArray(roles) ? roles.map(String) : [],
+      ...(row.org_id === null ? {} : { orgId: row.org_id }),
+    },
+    operation: row.operation,
+    kind: row.kind === 'action' ? 'action' : 'operation',
+    entity: row.entity,
+    entityId: row.entity_id,
+    permission: row.permission,
+    outcome,
+    reason: row.reason,
+    diff: Array.isArray(diff) ? (diff as readonly AuditFieldDiff[]) : [],
+  };
+};
+
+/**
+ * The `where` of one read, built from the predicates the query actually names — never
+ * `($1 is null or entity = $1)`, which hides the index from the planner. Every fragment is fixed
+ * text; only values are bound.
+ */
+function selectFor(query: AuditQuery, limit: number): { text: string; values: unknown[] } {
+  const where: string[] = [];
+  const values: unknown[] = [];
+  const bind = (value: unknown): string => {
+    values.push(value);
+    return `$${String(values.length)}`;
+  };
+  if (query.entity !== undefined) where.push(`entity = ${bind(query.entity)}`);
+  if (query.entityId !== undefined) where.push(`entity_id = ${bind(query.entityId)}`);
+  if (query.actorId !== undefined) where.push(`actor_id = ${bind(query.actorId)}`);
+  if (query.orgId !== undefined) where.push(`org_id = ${bind(query.orgId)}`);
+  if (query.before !== undefined) {
+    where.push(
+      `(at, id) < (${bind(query.before.at)}::timestamptz, ${bind(query.before.id)}::uuid)`,
+    );
+  }
+  if (query.changes === true) {
+    const reads = AUDIT_READ_OPERATIONS.map((operation) => bind(operation)).join(', ');
+    where.push(`(kind = 'action' or outcome <> 'allowed' or operation not in (${reads}))`);
+  }
+  const filter = where.length === 0 ? '' : ` where ${where.join(' and ')}`;
+  return {
+    text: `select ${COLUMNS} from ${ADMIN_AUDIT_TABLE}${filter} order by at desc, id desc limit ${bind(limit)}`,
+    values,
+  };
+}
+
+export interface PostgresAuditLogOptions {
+  /**
+   * The database to write to. Omitted — the ordinary case — it is the process's own (`db()`), so
+   * an entry joins whatever transaction is open and every role writes through the pool it booted.
+   */
+  readonly client?: DbClient;
+  /**
+   * Persist the reads that were allowed too — every list page, every row opened. Off by default:
+   * that is one insert per GET, and a trail of who LOOKED is a decision an app makes. A refused
+   * read is an event and is always written.
+   */
+  readonly reads?: boolean;
+  readonly sinks?: readonly AuditSink[];
+  readonly now?: () => Date;
+  /** Must answer a uuid: the column is one. Omitted, a time-ordered v7. */
+  readonly nextId?: () => string;
+}
+
+/**
+ * The audit log an admin names to keep its trail: `defineAdmin({ audit: postgresAuditLog() })`.
+ *
+ * One `insert` per entry, and `atomic` puts a write and its entry in one transaction — so a row
+ * never changes without the entry that says who changed it. A repository pinned to its own client
+ * cannot join that transaction (`X_REPO_CLIENT_PINNED`, raised before its first statement is
+ * sent): the write then runs as it would have with no log, and its entry follows it.
+ */
+export function postgresAuditLog(options: PostgresAuditLogOptions = {}): AuditLog {
+  const now = options.now ?? ((): Date => new Date());
+  const nextId = options.nextId ?? uuid;
+  const sinks = options.sinks ?? [];
+  const reads = options.reads === true;
+  // Resolved per statement, never captured: inside `atomic` it is the open transaction.
+  const client = (): DbClient => (options.client === undefined ? db() : options.client);
+
+  return {
+    kind: 'postgres',
+    async append(draft: AuditDraft): Promise<AuditEntry> {
+      const entry = auditEntry(draft, nextId(), now());
+      if (reads || !isAllowedRead(entry)) {
+        // A plain `{ text, values }`, the shape `pgExecutorFor` hands the same client: the text
+        // is this file's constant and every value is bound.
+        await client().query({
+          text: SQL_ADMIN_AUDIT_INSERT,
+          values: [
+            entry.id,
+            entry.at,
+            entry.requestId,
+            entry.actor.id,
+            JSON.stringify(entry.actor.roles),
+            entry.actor.orgId ?? null,
+            entry.operation,
+            entry.kind,
+            entry.entity,
+            entry.entityId,
+            entry.permission,
+            entry.outcome,
+            entry.reason,
+            // `jsonText`, not `JSON.stringify`: a `money()` diff holds a bigint, which the
+            // second throws on — after the write it describes has already happened.
+            jsonText(entry.diff),
+          ],
+        });
+      }
+      for (const sink of sinks) await sink.write(entry);
+      return entry;
+    },
+    async entries(query = {}): Promise<readonly AuditEntry[]> {
+      const select = selectFor(query, auditLimit(SUBJECT, query));
+      const rows = await client().query<AuditRow>(select);
+      return rows.map(entryOf);
+    },
+    async atomic<T>(run: () => Promise<T>): Promise<T> {
+      try {
+        return await withTransaction(
+          run,
+          options.client === undefined ? {} : { client: options.client },
+        );
+      } catch (error) {
+        if (isUltimateError(error) && error.code === 'X_REPO_CLIENT_PINNED') return run();
+        throw error;
+      }
+    },
+  };
+}

package/src/audit-schema.ts

@@ -0,0 +1,47 @@
+// The DDL of the admin's one framework table, and nothing else: a LEAF module, so the boot's
+// `FRAMEWORK_SCHEMA` (`@ultimat3/cli`) can apply it in every role through `@ultimat3/admin/schema`
+// without pulling one screen, one view or one stylesheet into a worker's module graph.
+
+/** The table. One name, read by this DDL and by `audit-pg.ts`'s insert and select. */
+export const ADMIN_AUDIT_TABLE = 'x_admin_audit';
+
+/**
+ * Applied by the boot (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`), never by an app migration — the rule
+ * every framework table follows. A plain table: there is no `appendOnly` entity modifier in this
+ * tree, so "append-only" is `audit-pg.ts` issuing an `insert` and a `select` and nothing else.
+ *
+ * **Two indexes.** `(entity, entity_id, at desc, id desc)` is the detail page's history card: one
+ * row's trail, newest first, a keyset seek with no sort. `(at desc, id desc)` is the audit screen.
+ * `actor_id` and `org_id` have none — both are filters over the second index's order, and an index
+ * is a write cost paid on every audited request.
+ *
+ * **`diff` is what the admin already redacted.** A sealed column and a `sensitive` field reach it
+ * as `[redacted]` (`crud-input.ts`'s `rowDiff`), so no plaintext is ever a value in this table.
+ *
+ * **No retention and no purge**, for `x_audit`'s reason: how long a trail is kept is a legal
+ * question with a different answer per app.
+ */
+export const SQL_ADMIN_AUDIT_TABLE = `
+create table if not exists x_admin_audit (
+  id          uuid        primary key,
+  at          timestamptz not null,
+  request_id  text        not null,
+  actor_id    text        not null,
+  actor_roles jsonb       not null,
+  org_id      text,
+  operation   text        not null,
+  kind        text        not null,
+  entity      text        not null,
+  entity_id   text,
+  permission  text        not null,
+  outcome     text        not null,
+  reason      text        not null,
+  diff        jsonb       not null,
+  recorded_at timestamptz not null default now()
+);
+
+create index if not exists x_admin_audit_entity_idx
+  on x_admin_audit (entity, entity_id, at desc, id desc);
+
+create index if not exists x_admin_audit_at_idx on x_admin_audit (at desc, id desc);
+`;