@ultimat3/admin 22.15.0 → 24.0.0

package/src/page-guard.tsx

@@ -1,13 +1,14 @@
-// The wrapper that makes a custom page's authz unskippable. `routes.ts` never hands the router
-// the author's component — it hands this one, which asks the SAME `decideAll` every CRUD call
-// and every nav item asks, audits the refusal, and only then calls the author's code.
+// What a refused screen renders and the audit entry it leaves. The wrapper that DECIDES is
+// `guardedScreen()` in `screen-frame.tsx`: `routes.ts` never hands a host the author's component
+// — it hands that screen, which asks the SAME `decideAll` every CRUD call and every nav item
+// asks, audits the refusal through this file, and only then calls the author's code.
 
 import { t } from '@ultimat3/i18n';
 import type { JSX } from 'solid-js';
-import type { AdminRoute } from './admin';
+import styles from './admin.module.scss';
 import { deniedDraft } from './audit';
-import { type AdminDecision, decideAll } from './authz';
-import type { AdminPageComponent, AdminPageProps } from './pages';
+import type { AdminDecision } from './authz';
+import type { CrudCtx } from './crud';
 
 /**
  * The refusal, rendered as the page. Not a redirect and not a 404: an operator who is missing a
@@ -21,7 +22,7 @@ export function AdminPageDenied(props: {
   return (
     <section class="x-admin-denied" role="alert">
       <h1>{t(props.titleKey)}</h1>
-      <p>
+      <p class={styles['refusal']}>
         {t('admin.denied.body', {
           permission: props.decision.permission,
           reason: props.decision.reason,
@@ -32,27 +33,23 @@ export function AdminPageDenied(props: {
 }
 
 /**
- * Wrap once, at route-table build time. The author's component is never reachable from
- * `adminRoutes()`, so "the page that forgot its policy line" has nowhere left to exist.
+ * The audit entry of a refused SCREEN. The page is the subject, so its path is what the row
+ * names — there is no entity and no row id to key a refused screen by. One writer, so a custom
+ * page and a generated form's GET leave the same entry.
  */
-export function guardedPage(route: AdminRoute, component: AdminPageComponent): AdminPageComponent {
-  return async (props: AdminPageProps): Promise<JSX.Element> => {
-    const decision = decideAll(props.ctx.authz, route.permissions, props.ctx.actor);
-    if (!decision.allowed) {
-      // The page IS the subject here, so its path is what the audit row names — there is no
-      // entity and no row id to key a refused screen by.
-      await props.ctx.audit.append(
-        deniedDraft({
-          requestId: props.ctx.requestId,
-          actor: props.ctx.actor,
-          operation: 'page',
-          kind: 'operation',
-          entity: route.path,
-          decision,
-        }),
-      );
-      return <AdminPageDenied titleKey={route.titleKey} decision={decision} />;
-    }
-    return component(props);
-  };
+export async function auditRefusal(
+  ctx: CrudCtx,
+  path: string,
+  decision: AdminDecision,
+): Promise<void> {
+  await ctx.audit.append(
+    deniedDraft({
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: 'page',
+      kind: 'operation',
+      entity: path,
+      decision,
+    }),
+  );
 }

package/src/pagination.ts

@@ -10,7 +10,8 @@ import { type AdminResource, repoOf } from './resource';
 
 export interface AdminCursor {
   readonly field: string;
-  readonly value: string;
+  /** The boundary row's sort value as text, or `null` when it holds none — a position too. */
+  readonly value: string | null;
   readonly id: string;
   readonly direction: 'after' | 'before';
 }
@@ -50,7 +51,7 @@ export function decodeAdminCursor(
     if (payload.key.length !== 3) return null;
     const [direction, field, value] = payload.key;
     if (direction !== 'after' && direction !== 'before') return null;
-    if (typeof field !== 'string' || typeof value !== 'string') return null;
+    if (typeof field !== 'string' || (typeof value !== 'string' && value !== null)) return null;
     return { direction, field, value, id: payload.id };
   } catch (error) {
     if (isUltimateError(error) && error.code === 'X_CURSOR_INVALID') return null;
@@ -98,10 +99,15 @@ export function listQuery<Row extends AdminRow>(
   };
 }
 
-const cursorValue = (row: AdminRow, field: string): string => {
+/**
+ * The boundary's sort value as the cursor carries it. A NULL stays `null` — JSON holds one — and
+ * is never `''`: an empty string is a text value of its own, and the seek past a NULL boundary
+ * reads the NULL rows, which a seek past `''` never reaches.
+ */
+const cursorValue = (row: AdminRow, field: string): string | null => {
   const value = row[field];
   if (value instanceof Date) return value.toISOString();
-  return value === null || value === undefined ? '' : String(value);
+  return value === null || value === undefined ? null : String(value);
 };
 
 /**

package/src/policy-bridge.ts

@@ -3,13 +3,26 @@
 // policies and the dashboard — and no second authz implementation can grow next to it.
 
 import { type Actor, userActor } from '@ultimat3/core';
-import { definePermissions, evaluate, type Policy } from '@ultimat3/policy';
-import { type AdminActor, type AdminAuthz, type AdminDecision, allowed, denied } from './authz';
+import {
+  can,
+  definePermissions,
+  evaluate,
+  isKnownPermission,
+  type KnownPermission,
+  type Permission,
+  type Policy,
+} from '@ultimat3/policy';
+import {
+  type AdminActor,
+  type AdminAuthz,
+  type AdminDecision,
+  type AdminSubject,
+  allowed,
+  denied,
+  impliersOf,
+} from './authz';
 import { ADMIN_PERMISSIONS } from './permissions';
 
-/** The admin's own permission set, registered with the policy layer at import time. */
-export const adminPermissions = definePermissions(ADMIN_PERMISSIONS);
-
 /**
  * The admin carries its own actor shape; @ultimat3/policy evaluates core's `Actor`. The
  * mapping lives here because this file is the only one allowed to speak to the policy layer.
@@ -27,15 +40,109 @@ const policyActor = (actor: AdminActor): Actor =>
 function readDecision(permission: string, result: unknown): AdminDecision {
   const bag = (typeof result === 'object' && result !== null ? result : {}) as {
     allowed?: unknown;
-    reason?: unknown;
+    decision?: unknown;
     trace?: unknown;
   };
+  // The reason lives on the evaluation's `decision`, not beside `allowed`. It was read off the top
+  // level, where no evaluation has ever carried one, so every refusal an operator read said
+  // `admin.policy.evaluated` — the same string whichever rule refused them.
+  const inner = (typeof bag.decision === 'object' && bag.decision !== null ? bag.decision : {}) as {
+    reason?: unknown;
+  };
   const verdict = result === true || bag.allowed === true;
-  const reason = typeof bag.reason === 'string' ? bag.reason : 'admin.policy.evaluated';
+  const reason = typeof inner.reason === 'string' ? inner.reason : 'admin.policy.evaluated';
   const trace = Array.isArray(bag.trace) ? bag.trace.map((line) => String(line)) : [];
   return verdict ? allowed(permission, reason, trace) : denied(permission, reason, trace);
 }
 
+/** `resource:verb` — the only shape `can()` takes. Anything else is denied, never thrown. */
+const isPermission = (value: string): value is Permission => /^[^:]+:[^:]+$/.test(value);
+
+/**
+ * Declare the admin's OWN permissions (`ADMIN_PERMISSIONS`) and the ones a mount DERIVES —
+ * `<entity>:read|write|delete`, a page's, an action's — so `can()` knows them. Granting them stays
+ * the app's: a role map that names none of these refuses every screen. Idempotent, and this file's
+ * because it is the one that speaks to `@ultimat3/policy`.
+ *
+ * Called by `defineAdmin()`, never at module scope. The permission registry is permissive while
+ * EMPTY and closed once it holds one name, so registering `admin:*` on import closed the set for
+ * every module that merely shared a process with this package — an app that imported the admin
+ * for a type, and every test file that ran after an admin one.
+ */
+export function declareAdminPermissions(permissions: readonly string[]): void {
+  definePermissions([...ADMIN_PERMISSIONS, ...permissions.filter(isPermission)]);
+}
+
+const evaluated = (
+  permission: string,
+  policy: Policy,
+  actor: AdminActor,
+  subject: AdminSubject | undefined,
+): AdminDecision => {
+  // `EvaluateArgs` carries exactly one payload. An admin subject with no action input IS
+  // that payload: a row-level rule has nothing but the entity and id to decide on.
+  const payload = subject?.input ?? subject;
+  // `row` is passed through only when the surface LOADED one. Omitting it and passing
+  // `row: undefined` are different facts to `evaluate`, and a rule that reads `row` must see
+  // `null` — "no row was loaded" — rather than a value the admin invented from `input`.
+  const row = subject === undefined || !('row' in subject) ? undefined : { row: subject.row };
+  return readDecision(
+    permission,
+    evaluate(policy, { actor: policyActor(actor), input: payload, ...row }),
+  );
+};
+
+/**
+ * The default authz: the app's ROLE MAP decides. Every permission the admin asks about is
+ * `can(permission)` — "does a role this actor holds grant it" — so an app with a `defineRoles()`
+ * call has a working, closed admin with no permission → policy table to keep in step. An app
+ * whose rules read the row or the tenant passes `policyAuthz({ policies })` instead.
+ */
+export function roleAuthz(): AdminAuthz {
+  return {
+    decide({ permission, actor, subject }): AdminDecision {
+      // Asked BEFORE `can()`, which throws on a name the registry lacks: a decision is an answer,
+      // and an undeclared permission is a refusal with its fix, never a 500 out of a nav render.
+      if (!isPermission(permission) || !isKnownPermission(permission)) {
+        return denied(permission, 'admin.policy.missing', [
+          `"${permission}" is not a declared resource:verb permission`,
+          `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
+        ]);
+      }
+      // `can()` asserts the name against the registry `declareAdminPermissions` filled. The cast
+      // is the same one a route guard's bare string takes: the registry, not the type, is the check.
+      const own = evaluated(permission, can(permission as KnownPermission), actor, subject);
+      if (own.allowed) return own;
+      // The admin's implications, as `staticAuthz` applies them: a role granting `admin:destroy`
+      // holds `admin:write` and `admin:read` too. Without this the same grants answered two ways.
+      for (const implier of impliersOf(permission)) {
+        const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
+        if (carried.allowed) {
+          return allowed(permission, carried.reason, [
+            ...carried.trace,
+            `${permission} is implied by ${implier}`,
+          ]);
+        }
+      }
+      return own;
+    },
+  };
+}
+
+/**
+ * ONE policy answers every gate the admin asks — "whoever may run the app may run its admin".
+ * The shape a small app starts in: a single grant its role map already has, with no table of
+ * per-entity permissions to keep in step as entities are added. The pair is still asked
+ * (`admin:write` then `posts:write`), each is still audited under its own name, and the day a
+ * view-only operator is needed this becomes `roleAuthz()` or `policyAuthz({ policies })`.
+ */
+export function singlePolicyAuthz(policy: Policy): AdminAuthz {
+  return {
+    decide: ({ permission, actor, subject }): AdminDecision =>
+      evaluated(permission, policy, actor, subject),
+  };
+}
+
 export interface PolicyAuthzInput {
   /** Permission name → the policy that decides it. `describeActions()` supplies these. */
   readonly policies: Readonly<Record<string, Policy>>;
@@ -55,17 +162,7 @@ export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
           `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
         ]);
       }
-      // `EvaluateArgs` carries exactly one payload. An admin subject with no action input IS
-      // that payload: a row-level rule has nothing but the entity and id to decide on.
-      const payload = subject?.input ?? subject;
-      // `row` is passed through only when the surface LOADED one. Omitting it and passing
-      // `row: undefined` are different facts to `evaluate`, and a rule that reads `row` must see
-      // `null` — "no row was loaded" — rather than a value the admin invented from `input`.
-      const row = subject === undefined || !('row' in subject) ? undefined : { row: subject.row };
-      return readDecision(
-        permission,
-        evaluate(policy, { actor: policyActor(actor), input: payload, ...row }),
-      );
+      return evaluated(permission, policy, actor, subject);
     },
   };
 }

package/src/registry.ts

@@ -6,7 +6,7 @@
 // is the compile-time proof that a real `entity()` result satisfies it; it is checked by
 // `tsc`, not asserted in a comment, because the admin used to read fields no entity had.
 
-import type { Entity, Repo } from '@ultimat3/entity';
+import type { Entity, Operator, Table } from '@ultimat3/entity';
 
 /**
  * What the author declared about one column — `@ultimat3/entity`'s `ColumnMeta`, narrowed to
@@ -37,11 +37,21 @@ export interface AdminColumnMeta {
    * hands back the resolved target — but its presence is what makes the column a foreign key.
    */
   readonly references?: () => unknown;
+  /**
+   * `.sealed()`: encrypted at rest, opened on read, absent from every schema that leaves the
+   * server. Present means the admin derives NO readable field for it — see `entity-columns.ts`.
+   */
+  readonly sealed?: { readonly lookup: boolean };
 }
 
 /** One column of a registered entity. An `@ultimat3/entity` `Column` satisfies this. */
 export interface AdminColumn {
   readonly $meta: AdminColumnMeta;
+  /**
+   * The column's own guard. Optional in this surface only because a hand-built fixture has none;
+   * every `entity()` column carries it, and `repo-entity.ts` parses a URL's id through it.
+   */
+  readonly $parse?: (value: unknown) => unknown;
 }
 
 /** One column of `$describe()` output. Money is the one property that becomes two of these. */
@@ -65,6 +75,12 @@ export interface AdminEntity {
   readonly $columns: Readonly<Record<string, AdminColumn>>;
   /** The Standard Schema the entity validates with; forms hand input straight to it. */
   readonly $schema: unknown;
+  /**
+   * The column the handle scopes every read and write by, or `null`. Optional in this surface only
+   * because a hand-built fixture has none; every `entity()` result carries it. The admin never
+   * renders it as an input — the acting actor's tenant is the only value it may hold.
+   */
+  readonly $tenantColumn?: string | null;
   /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
   $describe(): AdminEntityDescription;
 }
@@ -80,14 +96,63 @@ type Satisfies<Surface, T extends Surface> = T;
 export type RegisteredEntity = Satisfies<AdminEntity, Entity<AdminRow>>;
 
 /**
- * A repo as `@ultimat3/entity` registers it — deliberately NOT claimed to be an `AdminRepo`:
- * the verbs differ (`findMany`/`insert` vs `list`/`create`) and its cursor is an opaque signed
- * string where the admin speaks a keyset bound, so the host binds an adapter over it.
+ * The slice of a typed handle's read chain the admin drives — `database()`'s `db.<entity>`. Named
+ * for the reason `AdminEntity` is: one file changes when the handle grows, and `RegisteredTable`
+ * is the `tsc`-checked proof a real one satisfies it.
  */
-export type RegisteredRepo = Repo;
+export interface AdminTableRead {
+  where(filter: Readonly<Record<string, unknown>>): AdminTableRead;
+  andWhere(column: string, op: Operator, value?: unknown): AdminTableRead;
+  orderBy(column: string, direction?: 'asc' | 'desc'): AdminTableRead;
+  limit(rows: number): AdminTableRead;
+  all(): Promise<readonly AdminRow[]>;
+  one(): Promise<AdminRow | null>;
+  count(): Promise<number>;
+  /** Read for the entity NAME only: it is how a handle is matched to the entity it serves. */
+  plan(): { readonly entity: string };
+}
+
+/** One table of the app's typed handle. Tenancy, soft delete and sealing are its own. */
+export interface AdminTable extends AdminTableRead {
+  insert(values: Readonly<Record<string, unknown>>): Promise<AdminRow>;
+  update(id: string, patch: Readonly<Record<string, unknown>>): Promise<AdminRow>;
+  delete(id: string): Promise<void>;
+}
+
+/** The app's `database()` result, as `defineAdmin({ db })` takes it. Keys are the app's spelling. */
+export type AdminDb = Readonly<Record<string, AdminTable>>;
+
+/** The claim, checked: `database()`'s table IS an `AdminTable`. */
+export type RegisteredTable = Satisfies<AdminTable, Table<AdminRow>>;
+
+export type FilterOp =
+  | 'eq'
+  | 'neq'
+  | 'contains'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  /** `value: true` keeps the rows with no value, `value: false` the rows with one. */
+  | 'is-null';
 
-export type FilterOp = 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'in' | 'is-null';
+export const FILTER_OPS: readonly FilterOp[] = [
+  'eq',
+  'neq',
+  'contains',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'in',
+  'is-null',
+];
 
+/**
+ * One predicate of a list read. Every list the admin issues is a CONJUNCTION of these — the URL's
+ * filters, the scope's, and the resource's row scope — so each maps to one indexed comparison.
+ */
 export interface AdminFilter {
   readonly field: string;
   readonly op: FilterOp;
@@ -101,7 +166,8 @@ export interface AdminSort {
 
 export interface KeysetBound {
   readonly field: string;
-  readonly value: string;
+  /** The boundary row's sort value as text; `null` when it holds none, which sorts LAST. */
+  readonly value: string | null;
   readonly id: string;
 }
 
@@ -147,10 +213,33 @@ export interface AdminActionCtx {
   readonly timeZone: string;
 }
 
+/** How a batch action behaves past the size a request should run inline. */
+export interface AdminBatchOptions {
+  /**
+   * The most rows one request runs INLINE. A selection larger than this is handed to the queue —
+   * one `admin.batch` job per chunk — and the answer says how many rows were queued, not done.
+   */
+  readonly threshold: number;
+  /** Rows per queued job. Omitted: `threshold`. */
+  readonly chunk?: number;
+}
+
+/** What a set-based "all matching" answers — the shape of a store's own bulk verb. */
+export interface AdminMatchingResult {
+  /** Rows this call changed. */
+  readonly affected: number;
+  /** Rows still matching afterwards. Run again until it is zero. */
+  readonly remaining: number;
+}
+
 /**
  * A registered `action` as the admin surfaces it. `permission` is not optional: an action
  * with no policy is an open door, and the admin refuses to render one
  * (X_ADMIN_POLICY_MISSING).
+ *
+ * One declaration, every projection: the button on the detail page and on each list row, the
+ * action's own form, the batch bar, the MCP tool, the audit entry. `when` and `batch` narrow WHERE
+ * it appears and never add a second handler.
  */
 export interface AdminAction<Input = Readonly<Record<string, unknown>>, Output = unknown> {
   readonly name: string;
@@ -158,15 +247,47 @@ export interface AdminAction<Input = Readonly<Record<string, unknown>>, Output =
   /** The entity the button belongs to. Absent = a global action in the toolbar. */
   readonly entity?: string;
   readonly destructive?: boolean;
+  /** Absent: `admin.action.<name>` — `actionLabelKey`, the one spelling every screen reads. */
   readonly labelKey?: string;
   /** Mirrors the action's own `mcp` block; the admin MCP surface honours `expose`. */
   readonly mcp?: { readonly expose?: boolean; readonly description?: string };
-  /** The action's Standard Schema, handed to the form and to the MCP tool definition. */
+  /**
+   * The action's input schema — a `t.object({ … })`. Rendered as the action's form (one control
+   * per property), validated before the handler runs with each issue shown against its field,
+   * and handed to the MCP tool definition. Absent: the action takes no input, and its button is a
+   * confirm only. The row's `id` is the admin's own envelope and is never a property here.
+   */
   readonly input?: unknown;
+  /**
+   * Whether the action applies to THIS row. Decides the button on the detail page and on each
+   * list row, and is evaluated again on the server before the handler runs — a hidden button is
+   * not an authorization: `X_ADMIN_ACTION_NOT_APPLICABLE`. The row it reads carries no sealed
+   * column. Absent: the action applies to every row.
+   */
+  readonly when?: (row: AdminRow) => boolean;
+  /**
+   * In the list's batch bar: run once per selected row through the same gate as the button, each
+   * row audited, the answer counting done, refused and failed. `true` runs every batch inline;
+   * `{ threshold }` queues a selection larger than that as one job per chunk.
+   */
+  readonly batch?: true | AdminBatchOptions;
+  /**
+   * The batch bar's "all matching" as ONE set-based call instead of a walk of rows: handed the
+   * list's own `where` — row scope, then scope, then filters — it changes what matches and answers
+   * how many it changed and how many still match. For a store with a bounded bulk verb of its own
+   * (the jobs operator's `requeueMany`). Decided and audited once, for the set; the per-row gate is
+   * not asked per row, so the verb's own predicate is where `when` holds. A checked selection
+   * still runs row by row through `handle`. Requires `batch`.
+   */
+  readonly matching?: (args: {
+    readonly where: readonly AdminFilter[];
+    readonly input: Input;
+    readonly ctx: AdminActionCtx;
+  }) => Promise<AdminMatchingResult>;
   handle(args: { input: Input; ctx: AdminActionCtx }): Promise<Output>;
 }
 
-/** A registered `job` as the admin's Jobs page needs it — `describeJobs()` output. */
+/** A registered `job` as an AI pane is told about it (`ai-panes.ts`) — `describeJobs()` output. */
 export interface AdminJobSummary {
   readonly name: string;
   readonly queue?: string;
@@ -185,3 +306,13 @@ export function rowId(row: AdminRow, idField: string): string {
   const value = row[idField];
   return typeof value === 'string' ? value : String(value ?? '');
 }
+
+/**
+ * A row as something DRAWN or DECIDED on reads it: its enumerable values, minus every sealed
+ * column. A repository row keeps a sealed property off its enumerable set already; a hand-written
+ * `repo:` may not, so the names are dropped explicitly — a computed cell is rendered and an
+ * action's `when` is evaluated per row, and a sealed value reaches neither.
+ */
+export function computedRow(row: AdminRow, sealed: readonly string[]): AdminRow {
+  return Object.fromEntries(Object.entries(row).filter(([key]) => !sealed.includes(key)));
+}

package/src/related.ts

@@ -0,0 +1,105 @@
+// A row's RELATED rows: the `hasMany` relations a resource names in `related`, each read as the
+// related resource's own list — its gate, its row scope, its columns — narrowed to the rows that
+// point at this one. No second table is declared anywhere: the related resource already is one.
+
+import { relationsFor as entityRelationsFor } from '@ultimat3/entity';
+import { adminList, type CrudCtx, canOperate } from './crud';
+import { AdminFieldUnsupportedError } from './errors';
+import type { AdminPage } from './pagination';
+import type { AdminFilter, AdminRow } from './registry';
+import type { AdminResource } from './resource';
+
+/** How many related rows a detail page shows per relation. The rest are one link away. */
+export const RELATED_PAGE_SIZE = 10;
+
+/** One declared relation, resolved against the admin it is declared in. */
+export interface AdminRelated {
+  /** The relation's name on the entity — what `related: [...]` spelled. */
+  readonly name: string;
+  /** The resource whose rows these are. */
+  readonly resource: AdminResource;
+  /** The property of THAT resource holding the foreign key. */
+  readonly field: string;
+  /** The property of the row in hand the foreign key points at. */
+  readonly localKey: string;
+}
+
+/**
+ * The `related` names of one resource, resolved. Every name is a `hasMany` of the entity whose
+ * target is a resource of this admin — anything else is refused here, where it is declared, never
+ * drawn as an empty card.
+ */
+export function relatedOf(
+  resources: readonly AdminResource[],
+  resource: AdminResource,
+): readonly AdminRelated[] {
+  if (resource.related.length === 0) return [];
+  // The one read of `@ultimat3/entity`'s relations in this package: the FK already written IS
+  // the relation, so the admin derives nothing of its own and names nothing twice.
+  const relations = entityRelationsFor(resource.name);
+  const offered = Object.values(relations)
+    .filter((relation) => relation.kind === 'hasMany')
+    .map((relation) => relation.name);
+  const hint = `resources.${resource.name}.related may name: ${offered.length > 0 ? offered.join(', ') : 'nothing — no entity references this one'}`;
+
+  return resource.related.map((name) => {
+    const refuse = (cause: string, fix: string): never => {
+      throw new AdminFieldUnsupportedError({ entity: resource.name, field: name, cause, fix });
+    };
+    const relation = Object.hasOwn(relations, name) ? relations[name] : undefined;
+    if (relation === undefined) {
+      return refuse('named in related and is not a relation of the entity', hint);
+    }
+    if (relation.kind !== 'hasMany') {
+      return refuse(
+        `named in related and is a belongsTo: the "${relation.localKey}" field already links to its row`,
+        hint,
+      );
+    }
+    const target = resources.find((known) => known.name === relation.to);
+    if (target === undefined) {
+      return refuse(
+        `named in related, and its rows are "${relation.to}", which is not a resource of this admin`,
+        `add the ${relation.to} entity to defineAdmin({ entities }) — its own list is what related draws`,
+      );
+    }
+    return { name, resource: target, field: relation.remoteKey, localKey: relation.localKey };
+  });
+}
+
+/** One related list as the detail page draws it. */
+export interface AdminRelatedList {
+  readonly related: AdminRelated;
+  readonly page: AdminPage<AdminRow>;
+  /** The one predicate that makes this list THIS row's. */
+  readonly filter: AdminFilter;
+}
+
+/**
+ * The related lists of one row — one statement each, read beside each other. A related resource
+ * this actor may not list is LEFT OUT, silently: they asked for this row, and the refusal they
+ * would get by opening that list is logged there. Everything else is `adminList`: the related
+ * resource's policy decides, its `rows` narrows, and the read is audited under its own name.
+ */
+export async function relatedLists(
+  related: readonly AdminRelated[],
+  row: AdminRow,
+  ctx: CrudCtx,
+): Promise<readonly AdminRelatedList[]> {
+  const readable = related.filter((one) => canOperate(one.resource, 'list', ctx));
+  const read = await Promise.all(
+    readable.map(async (one): Promise<AdminRelatedList | null> => {
+      const key = row[one.localKey];
+      if (key === null || key === undefined) return null;
+      const filter: AdminFilter = { field: one.field, op: 'eq', value: String(key) };
+      const result = await adminList<AdminRow>(one.resource, ctx, {
+        // No scope, not even the default one: a related row counts whatever tab it sits under.
+        scope: null,
+        filters: [filter],
+        limit: RELATED_PAGE_SIZE,
+      });
+      return result.ok ? { related: one, page: result.page, filter } : null;
+    }),
+  );
+  return read.filter((one): one is AdminRelatedList => one !== null);
+}