@ultimat3/admin 23.0.0 → 25.0.0

package/src/mcp.ts

@@ -3,13 +3,7 @@
 // confirmation rules as the buttons — this file adds a transport, not a second back door.
 
 import type { Actor } from '@ultimat3/core';
-import {
-  agentActor,
-  createContext,
-  hasContext,
-  runWithContext,
-  withChildContext,
-} from '@ultimat3/core';
+import { agentActor, ctxOf, hasContext, runWithContext, withChildContext } from '@ultimat3/core';
 import {
   type AnyMcpTool,
   type AppMcp,
@@ -39,6 +33,7 @@ import {
 import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
 import { type AskedFilter, checkedFilter } from './list-filters';
+import { adminTokenScopes, adminToolScopes } from './mcp-scopes';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import type { AdminAction, AdminRow } from './registry';
 import { adminSearch } from './search';
@@ -234,13 +229,29 @@ function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
   if (result.kind === 'missing') {
     return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
   }
+  // Reached only by a caller that sent a version; the update tool sends none.
+  if (result.kind === 'stale') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'the row changed since it was read' };
+  }
   return invalidIssues(result.issues);
 }
 
+/**
+ * What a session token resolves to: the actor, and optionally the admin scopes the TOKEN was
+ * issued for — narrower than the actor, never wider (the actor's policy still decides each tool).
+ * `['admin:read']` is a read-only token: list, read, search and `readonly` actions. Absent: the
+ * token is as strong as its actor (`adminTokenScopes`). Named `tokenScopes`, not `scopes`, because
+ * core's `Actor.scopes` is a different thing (framework capabilities) and an actor handed straight
+ * through must not have its `[]` read as "this token may do nothing".
+ */
+export interface AdminMcpActor extends AdminActor {
+  readonly tokenScopes?: readonly string[];
+}
+
 export interface AdminMcpOptions {
   readonly app: AdminApp;
   /** Resolve the MCP session's actor. The same hook the HTTP surface uses, never a bypass. */
-  actor(session: { readonly token?: string }): Promise<AdminActor | null> | AdminActor | null;
+  actor(session: { readonly token?: string }): Promise<AdminMcpActor | null> | AdminMcpActor | null;
   readonly requestId?: () => string;
 }
 
@@ -370,7 +381,7 @@ function allowedToolNames(
 const asCaller = <T>(actor: Actor, requestId: string, run: () => Promise<T>): Promise<T> =>
   hasContext()
     ? withChildContext({ actor }, run)
-    : runWithContext(createContext({ actor, requestId }), run);
+    : runWithContext(ctxOf({ actor, requestId }), run);
 
 function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMcpTool): AnyMcpTool {
   return {
@@ -421,10 +432,15 @@ function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMc
  */
 export function adminMcp(opts: AdminMcpOptions): AppMcp {
   const requestId = opts.requestId ?? ((): string => crypto.randomUUID());
+  const catalog = adminToolCatalog(opts.app);
 
   return defineAppMcp({
     name: 'admin',
-    tools: adminToolCatalog(opts.app).map((tool) => toMcpTool(opts, requestId, tool)),
+    tools: catalog.map((tool) => toMcpTool(opts, requestId, tool)),
+    // The connection gate: each tool needs its admin-level permission as a token scope, checked
+    // by the registry BEFORE the actor's policy. A stdio host builds its caller's scopes with
+    // `adminTokenScopes`, as `resolveToken` does below.
+    scopes: adminToolScopes(catalog),
     async resolveToken(token: string): Promise<ResolvedToken | null> {
       const actor = await opts.actor({ token });
       // `kind: 'agent'` — the same actor shape an agent gets everywhere else, so a policy
@@ -438,7 +454,7 @@ export function adminMcp(opts: AdminMcpOptions): AppMcp {
         ? null
         : {
             actor: agentActor({ id: actor.id, roles: actor.roles ?? [], orgId: actor.orgId }),
-            scopes: new Set(),
+            scopes: adminTokenScopes(actor.tokenScopes),
           };
     },
   });

package/src/pagination.ts

@@ -3,14 +3,16 @@
 // otherwise skip and repeat rows, and every page would re-scan everything before it.
 // The position itself is encoded by `@ultimat3/core` — one signed cursor format, framework-wide.
 
-import { decodeCursor, encodeCursor, isUltimateError } from '@ultimat3/core';
+import type { Page } from '@ultimat3/core';
+import { decodeCursor, encodeCursor, isUltimateError, pageOf } from '@ultimat3/core';
 import type { AdminFilter, AdminListQuery, AdminRow, AdminSort } from './registry';
 import { rowId } from './registry';
 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 +52,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;
@@ -65,15 +67,16 @@ export interface PageRequest {
   readonly where?: readonly AdminFilter[];
 }
 
-export interface AdminPage<Row extends AdminRow> {
-  readonly rows: readonly Row[];
+/**
+ * `@ultimat3/core`'s `Page` — `hasMore` (a page exists AFTER this one, what the Next control is
+ * enabled by, in both directions) and `nextCursor` (`null` exactly when it is false) — plus what
+ * only a screen pages by: the sort, the size, and the cursor that walks BACK.
+ */
+export type AdminPage<Row extends AdminRow> = Page<Row> & {
   readonly sort: AdminSort;
   readonly pageSize: number;
-  readonly nextCursor: string | null;
   readonly prevCursor: string | null;
-  /** A page exists AFTER this one — what the Next control is enabled by, in both directions. */
-  readonly hasMore: boolean;
-}
+};
 
 /** The repo query for one page. Asks for `limit + 1` to learn whether a next page exists. */
 export function listQuery<Row extends AdminRow>(
@@ -98,10 +101,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);
 };
 
 /**
@@ -141,20 +149,22 @@ export function pageFrom<Row extends AdminRow>(
   const hasMore = backwards ? true : overflow;
   const hasPrevious = backwards ? overflow : incoming !== null;
 
-  return {
+  // `pageOf` derives `hasMore` from the cursor, so Next is enabled exactly when it leads somewhere.
+  const next = pageOf(
     rows,
+    hasMore && last !== undefined
+      ? encodeAdminCursor(resource, {
+          direction: 'after',
+          field: sort.field,
+          value: cursorValue(last, sort.field),
+          id: rowId(last, resource.idField),
+        })
+      : null,
+  );
+  return {
+    ...next,
     sort,
     pageSize,
-    hasMore,
-    nextCursor:
-      hasMore && last !== undefined
-        ? encodeAdminCursor(resource, {
-            direction: 'after',
-            field: sort.field,
-            value: cursorValue(last, sort.field),
-            id: rowId(last, resource.idField),
-          })
-        : null,
     prevCursor:
       hasPrevious && first !== undefined
         ? encodeAdminCursor(resource, {

package/src/policy-bridge.ts

@@ -17,15 +17,12 @@ import {
   type AdminAuthz,
   type AdminDecision,
   type AdminSubject,
-  allowed,
-  denied,
+  adminAllowed,
+  adminDenied,
   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.
@@ -55,20 +52,25 @@ function readDecision(permission: string, result: unknown): AdminDecision {
   const verdict = result === true || bag.allowed === true;
   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);
+  return verdict ? adminAllowed(permission, reason, trace) : adminDenied(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 permissions an admin 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`.
+ * 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(permissions.filter(isPermission));
+  definePermissions([...ADMIN_PERMISSIONS, ...permissions.filter(isPermission)]);
 }
 
 const evaluated = (
@@ -102,7 +104,7 @@ export function roleAuthz(): AdminAuthz {
       // 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', [
+        return adminDenied(permission, 'admin.policy.missing', [
           `"${permission}" is not a declared resource:verb permission`,
           `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
         ]);
@@ -116,7 +118,7 @@ export function roleAuthz(): AdminAuthz {
       for (const implier of impliersOf(permission)) {
         const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
         if (carried.allowed) {
-          return allowed(permission, carried.reason, [
+          return adminAllowed(permission, carried.reason, [
             ...carried.trace,
             `${permission} is implied by ${implier}`,
           ]);
@@ -155,7 +157,7 @@ export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
     decide({ permission, actor, subject }): AdminDecision {
       const policy = input.policies[permission];
       if (policy === undefined) {
-        return denied(permission, 'admin.policy.missing', [
+        return adminDenied(permission, 'admin.policy.missing', [
           `no policy registered for "${permission}"`,
           `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
         ]);

package/src/registry.ts

@@ -166,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;
 }
 
@@ -246,6 +247,13 @@ 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;
+  /**
+   * The action changes nothing — an export, a verification, a recount — so its admin-level gate is
+   * `admin:read` rather than `admin:write`, and a read-only staff role (or an `admin:read` MCP
+   * token) may run it. `destructive` and `matching` (a set-based write) win over it: the stricter
+   * gate is the one that applies.
+   */
+  readonly readonly?: 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`. */

package/src/related.ts

@@ -2,7 +2,7 @@
 // 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 { relationsFor } from '@ultimat3/entity';
 import { adminList, type CrudCtx, canOperate } from './crud';
 import { AdminFieldUnsupportedError } from './errors';
 import type { AdminPage } from './pagination';
@@ -36,7 +36,7 @@ export function relatedOf(
   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 relations = relationsFor(resource.name);
   const offered = Object.values(relations)
     .filter((relation) => relation.kind === 'hasMany')
     .map((relation) => relation.name);

package/src/relations.ts

@@ -4,6 +4,7 @@
 // page, never one per row and never one per cell.
 
 import { finiteCount } from '@ultimat3/core';
+import { expectedQueryLoop } from '@ultimat3/db';
 import type { AuditEntry } from './audit';
 import type { AdminDecision } from './authz';
 import { type CrudCtx, decideOperation } from './crud';
@@ -26,7 +27,11 @@ export interface AdminOption {
  */
 export const LOOKUP_SELECT_MAX = 50;
 
-/** The most ids one label read names — the list's own page-size ceiling. */
+/**
+ * The most ids one label read names — the list's own page-size ceiling. A page naming more is read
+ * in chunks of this many, never cut at it: a 200-row list with two columns on one target names up
+ * to 400 ids, and the ids past the cut were drawn as raw ids with no error anywhere.
+ */
 const MAX_LABEL_IDS = 200;
 
 /** The row's label-field value when it is text, else its id — never a blank cell. */
@@ -140,7 +145,7 @@ async function relationOf(
   const visible = rowWhere(resource, ctx.actor);
   const labels = new Map<string, string>();
   let options: readonly AdminOption[] | null = null;
-  let wanted = [...need.ids].slice(0, MAX_LABEL_IDS);
+  let wanted = [...need.ids];
 
   if (need.pick) {
     // One over the ceiling: the extra row is how "small enough for a select" is learned without
@@ -162,14 +167,25 @@ async function relationOf(
     }
   }
 
-  if (wanted.length > 0) {
-    const rows = await repo.list({
-      where: [...visible, { field: resource.idField, op: 'in', value: wanted }],
-      sort: resource.defaultSort,
-      limit: wanted.length,
-    });
-    for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+  const chunks: string[][] = [];
+  for (let at = 0; at < wanted.length; at += MAX_LABEL_IDS) {
+    chunks.push(wanted.slice(at, at + MAX_LABEL_IDS));
   }
+  // One statement per chunk, and only past the ceiling: a page's ids are known up front, so this
+  // is a bounded batch, not a read per row — and declared as one.
+  await expectedQueryLoop(
+    'admin labels read a page’s referenced ids in chunks under the `in` ceiling',
+    async () => {
+      for (const chunk of chunks) {
+        const rows = await repo.list({
+          where: [...visible, { field: resource.idField, op: 'in', value: chunk }],
+          sort: resource.defaultSort,
+          limit: chunk.length,
+        });
+        for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+      }
+    },
+  );
 
   await readEntry(resource, ctx, decision);
   return { labels, options };
@@ -180,7 +196,7 @@ async function relationOf(
  * per target — two for a picked target too large for a `<select>` — whatever the page's row count
  * and however many columns point at the same target.
  */
-export async function relationsFor(
+export async function relationDataFor(
   resources: readonly AdminResource[],
   ctx: CrudCtx,
   needs: ReadonlyMap<string, RelationNeed>,

package/src/repo-entity.ts

@@ -5,6 +5,7 @@
 import { isUltimateError } from '@ultimat3/core';
 import { getEntity, invariantViolated } from '@ultimat3/entity';
 import { adminColumnsOf } from './entity-columns';
+import { seekPage } from './keyset-seek';
 import type {
   AdminDb,
   AdminEntity,
@@ -41,18 +42,21 @@ const literal = (text: string): string => text.replace(/[\\%_]/g, (wild) => `\\$
  * A comparison value, in the shape the column holds. An instant travels as ISO text — in a URL, in
  * a cursor — and the handle is given the `Date`: Postgres would cast the text, the memory driver
  * compares a `Date` to a string by its characters, and a keyset over `createdAt` (the admin's
- * default sort) then answers page one for every page.
+ * default sort) then answers page one for every page. An `integer` travels as text in a cursor
+ * too, and the memory driver's `eq` holds `'7'` and `7` to be two values where Postgres binds one.
  */
 type Typed = (field: string, value: unknown) => unknown;
 
 const typedBy = (entity: AdminEntity): Typed => {
-  const instants = new Set(
-    adminColumnsOf(entity)
-      .filter((column) => column.kind === 'timestamptz')
-      .map((column) => column.name),
-  );
+  const kinds = new Map(adminColumnsOf(entity).map((column) => [column.name, column.kind]));
   return (field, value) => {
-    if (typeof value !== 'string' || !instants.has(field)) return value;
+    if (typeof value !== 'string') return value;
+    const kind = kinds.get(field);
+    if (kind === 'integer') {
+      const count = Number(value);
+      return value.trim() !== '' && Number.isSafeInteger(count) ? count : value;
+    }
+    if (kind !== 'timestamptz') return value;
     const at = new Date(value);
     return Number.isNaN(at.getTime()) ? value : at;
   };
@@ -81,37 +85,6 @@ const filtered = (
   typed: Typed,
 ): AdminTableRead => where.reduce(predicate(typed), read);
 
-/**
- * `after`+asc and `before`+desc walk forward; the other two walk back. Written as one XOR rather
- * than a four-branch table, because the four branches are the same fact said twice.
- *
- * `gte`/`lte`, not `gt`/`lt`: rows sharing the boundary's sort value are still on the far side of
- * it, and `dropThroughTie` below is what removes the ones already served.
- */
-const sought = (read: AdminTableRead, query: AdminListQuery, typed: Typed): AdminTableRead => {
-  const bound = query.after ?? query.before;
-  if (bound === undefined) return read;
-  const forward = (query.after !== undefined) !== (query.sort.direction === 'desc');
-  // The bound is the STRING the cursor carried (`pagination.ts` writes a Date as ISO).
-  return read.andWhere(bound.field, forward ? 'gte' : 'lte', typed(bound.field, bound.value));
-};
-
-/**
- * Drop everything up to and including the cursor row. A typed chain cannot express the row-value
- * comparison `(sort, id) > (value, id)` a keyset needs, and the alternative — a strict `gt` on the
- * sort column alone — silently skips every row that ties with the boundary.
- */
-const dropThroughTie = (
-  rows: readonly AdminRow[],
-  query: AdminListQuery,
-  idField: string,
-): readonly AdminRow[] => {
-  const bound = query.after ?? query.before;
-  if (bound === undefined) return rows;
-  const at = rows.findIndex((row) => String(row[idField]) === bound.id);
-  return at === -1 ? rows : rows.slice(at + 1);
-};
-
 /**
  * One entity + its table → one `AdminRepo`.
  *
@@ -124,6 +97,7 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
   const idField = entity.$primaryKey[0] ?? 'id';
   const idColumn = Object.hasOwn(entity.$columns, idField) ? entity.$columns[idField] : undefined;
   const typed = typedBy(entity);
+  const columns = adminColumnsOf(entity);
   /**
    * `AdminRepo` carries `id: string` — a URL param, untyped by nature. The primary key column's
    * OWN `$parse` is what earns the crossing: `/posts/nope` is judged here, at the door, instead
@@ -152,14 +126,31 @@ export function adminRepoFor(entity: AdminEntity, table: AdminTable): AdminRepo<
 
   return {
     async list(query: AdminListQuery): Promise<readonly AdminRow[]> {
-      const rows = await sought(filtered(table, query.where ?? [], typed), query, typed)
-        .orderBy(query.sort.field, query.sort.direction)
-        // The tie-break, always: a page boundary on a partial order repeats or drops a row.
-        .orderBy(idField, query.sort.direction)
-        // One over the requested page so the tie-drop cannot hand back a short page.
-        .limit(query.limit + 1)
-        .all();
-      return dropThroughTie(rows, query, idField).slice(0, query.limit);
+      const base = filtered(table, query.where ?? [], typed);
+      const sortField = query.sort.field;
+      const facts = columns.find((column) => column.name === sortField);
+      return seekPage(
+        query,
+        {
+          field: sortField,
+          idField,
+          nullable: facts?.nullable ?? true,
+          instant: facts?.kind === 'timestamptz',
+          typed: (value) => typed(sortField, value),
+        },
+        async (where, order, limit) => {
+          const read = where.reduce(
+            (chain, term) =>
+              term.value === undefined
+                ? chain.andWhere(term.field, term.op)
+                : chain.andWhere(term.field, term.op, term.value),
+            base,
+          );
+          // The tie-break, always: a page boundary on a partial order repeats or drops a row.
+          const sorted = order.by === 'pair' ? read.orderBy(sortField, order.direction) : read;
+          return [...(await sorted.orderBy(idField, order.direction).limit(limit).all())];
+        },
+      );
     },
     // `async`, so a refused id arrives as a rejection: these return promises, and a caller that
     // chains `.catch()` instead of `await`ing would never see a synchronous throw.

package/src/resource-list.ts

@@ -94,6 +94,12 @@ interface Declared {
   readonly entity: AdminEntity;
 }
 
+/**
+ * The list URL's spelling of "no scope, not even the default" — `?scope=*`, what a related card's
+ * "all" link opens. Reserved: a scope declared under it is refused, so the word means one thing.
+ */
+export const NO_SCOPE = '*';
+
 /** The declared scopes, in declaration order — which is the order the tabs are drawn in. */
 export function scopesOf(
   resource: Declared,
@@ -105,6 +111,9 @@ export function scopesOf(
   const refuse = (asked: string, cause: string): never => {
     throw new AdminFilterInvalidError({ entity: resource.name, asked, cause, known: names });
   };
+  if (Object.hasOwn(scopes ?? {}, NO_SCOPE)) {
+    refuse(`scopes.${NO_SCOPE}`, `is the list URL's word for "no scope" and cannot name one`);
+  }
   const defaults = entries.filter(([, scope]) => scope.default === true).map(([name]) => name);
   if (defaults.length > 1) {
     refuse(

package/src/resource.ts

@@ -69,6 +69,13 @@ export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
    * At most one `default: true`; `count: true` is one extra query per tab that asks for it.
    */
   readonly scopes?: Readonly<Record<string, AdminScopeOptions>>;
+  /**
+   * Show this resource's row count on the `/admin` home. Opt-in, as a scope tab's `count` is: the
+   * figure is one full `count()` over the actor's rows on EVERY visit to the front page, so on a
+   * big table any operator reloading it is a load generator. Absent: no tile, the resource is still
+   * listed in the permission matrix.
+   */
+  readonly count?: boolean;
   /**
    * The rows this ACTOR may see at all. Applied to every read of the resource — list, search,
    * detail, lookup, labels, MCP — so it is the one place a second audience is declared.
@@ -134,6 +141,8 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   readonly columns: readonly AdminComputedColumn[];
   /** Declared scopes, in tab order. Empty for a resource that declares none. */
   readonly scopes: readonly AdminScope[];
+  /** The `/admin` home counts this resource — `count: true` declared. */
+  readonly count: boolean;
   /** `rows`, validated per call. Absent for a resource every permitted actor sees whole. */
   readonly rowScope?: AdminRowScope;
   /** The detail page's groups. Always at least one: undeclared fields have a default section. */
@@ -309,6 +318,7 @@ export function adminResource<Row extends AdminRow = AdminRow>(
     searchFields: fields.filter((field) => field.searchable),
     columns: computedColumnsOf(declared, opts.columns),
     scopes: scopesOf(declared, opts.scopes, opts.repo),
+    count: opts.count === true,
     ...(rowScope === undefined ? {} : { rowScope }),
     sections: layoutOf(
       {

package/src/row-version.ts

@@ -0,0 +1,20 @@
+// The version an edit form is rendered against: a keyed fingerprint of the row as it was READ,
+// posted back in a hidden field, so `adminUpdate` can tell "the row I was shown" from "the row as
+// it is now" and refuse a write that would silently overwrite a concurrent edit.
+
+import { keyedFingerprint } from '@ultimat3/core';
+import type { AdminRow } from './registry';
+
+/** The posted name of the version, beside `_operation`: never a column, never an input field. */
+export const VERSION_FIELD = '_version';
+
+/** The key a write against a stale version is refused and audited with. */
+export const ROW_CHANGED_REASON = 'admin.error.row-changed';
+
+/**
+ * Every value the row enumerates — a sealed one is non-enumerable and is not in it, so a password
+ * change is not a "concurrent edit" and no sealed value is ever folded into page text. Keyed: the
+ * page carries it, and an unkeyed hash of a row is an offline oracle for a short value in a column
+ * the form does not draw.
+ */
+export const rowVersion = (row: AdminRow): string => keyedFingerprint(row, 'admin.row-version');