@ultimat3/admin 23.0.0 → 24.0.0

package/src/jobs/fleet-repo.ts

@@ -14,18 +14,30 @@ const comparable = (value: unknown): string | number => {
   if (value instanceof Date) return value.getTime();
   if (typeof value === 'number') return value;
   if (typeof value === 'boolean') return value ? 1 : 0;
-  return value === null || value === undefined ? '' : String(value);
+  return String(value);
 };
 
-/** Code-unit order, never a collation: the same set reads the same way on every machine. */
+const absent = (value: unknown): boolean => value === null || value === undefined;
+
+/**
+ * Code-unit order, never a collation: the same set reads the same way on every machine. NULL is
+ * the LARGEST value — last ascending, first descending — as the database orders a nullable sort
+ * key and as `repo-entity.ts` seeks one; it read as `''` here, which sorted it as a zero.
+ */
 const order = (a: unknown, b: unknown): number => {
+  if (absent(a) || absent(b)) return absent(a) && absent(b) ? 0 : absent(a) ? 1 : -1;
   const x = comparable(a);
   const y = comparable(b);
   return x < y ? -1 : x > y ? 1 : 0;
 };
 
-/** A cursor carries its value as text (`pagination.ts`); read back as the column's own type. */
+/**
+ * A cursor carries its value as text (`pagination.ts`), or `null` for a row that held none; read
+ * back as the type of the row it is compared with. A `null` bound stays `null` — `new Date(null)`
+ * is the epoch and `new Date('')` is NaN, and either made the page after a NULL row the wrong one.
+ */
 const boundValue = (row: AdminRow, bound: KeysetBound, field: string): unknown => {
+  if (bound.value === null) return null;
   const held = row[field];
   if (held instanceof Date) return new Date(bound.value);
   if (typeof held === 'number') return Number(bound.value);

package/src/jobs/job-repo.ts

@@ -1,9 +1,15 @@
-// The job rows as an `AdminRepo`: a page is ONE `JobIntrospection.list` call, newest first and
-// keyset by `(createdAt, id)` — the store's own order, and the only one it answers — and a detail
-// is the store's own trace, its input already redacted. Read-only: every change is an action.
+// The job rows as an `AdminRepo`: a page is the store's own `JobIntrospection.list`, newest first
+// and keyset by `(createdAt, id)` — the only order it answers — and a detail is the store's own
+// trace, its input already redacted. Read-only: every change is an action.
 
 import { assert } from '@ultimat3/core';
-import { inspectJob, type JobRecord, jobCursor, MAX_JOB_PAGE } from '@ultimat3/jobs';
+import {
+  inspectJob,
+  type JobFilter,
+  type JobRecord,
+  jobCursor,
+  MAX_JOB_PAGE,
+} from '@ultimat3/jobs';
 import { AdminFilterInvalidError } from '../errors';
 import type { AdminListQuery, AdminRepo, AdminRow, KeysetBound } from '../registry';
 import { JOBS_RESOURCE, jobWhere } from './job-where';
@@ -37,7 +43,12 @@ export function jobRow(record: JobRecord): AdminRow {
 
 /** A keyset bound as the store's cursor: the bound row's instant in ms, and its id. */
 const cursorOf = (bound: KeysetBound): string =>
-  jobCursor({ createdAt: Date.parse(bound.value), id: bound.id });
+  // `createdAt` is never NULL on a job row, so a bound without a value names no position: `NaN`
+  // here, which the store refuses as an unreadable cursor rather than seeking from the epoch.
+  jobCursor({
+    createdAt: bound.value === null ? Number.NaN : Date.parse(bound.value),
+    id: bound.id,
+  });
 
 function assertOrder(query: AdminListQuery): void {
   const { field, direction } = query.sort;
@@ -50,23 +61,46 @@ function assertOrder(query: AdminListQuery): void {
   });
 }
 
+/**
+ * The rows one admin query asks for. The admin asks ONE row past its page to learn whether a next
+ * one exists, and the store answers `MAX_JOB_PAGE` at most — so a 200-row page (the admin's own
+ * ceiling, and what the MCP list tool accepts) was answered 200 rows, read as "no more", and every
+ * row after it was on no page. Past the store's ceiling, the overflow is a second read from where
+ * the first one stopped: after its last row walking forward, before its first walking back.
+ */
+async function records(filter: JobFilter, query: AdminListQuery): Promise<readonly JobRecord[]> {
+  const { introspect } = jobsOperator();
+  const backward = query.before !== undefined;
+  const bound =
+    query.after !== undefined
+      ? { after: cursorOf(query.after) }
+      : query.before !== undefined
+        ? { before: cursorOf(query.before) }
+        : {};
+  const first = await introspect.list({
+    ...filter,
+    limit: Math.min(query.limit, MAX_JOB_PAGE),
+    ...bound,
+  });
+  const over = query.limit - MAX_JOB_PAGE;
+  if (over <= 0 || first.length < MAX_JOB_PAGE) return first;
+  const edge = backward ? first[0] : first[first.length - 1];
+  if (edge === undefined) return first;
+  const more = await introspect.list({
+    ...filter,
+    limit: Math.min(over, MAX_JOB_PAGE),
+    ...(backward ? { before: jobCursor(edge) } : { after: jobCursor(edge) }),
+  });
+  return backward ? [...more, ...first] : [...first, ...more];
+}
+
 async function list(query: AdminListQuery): Promise<readonly AdminRow[]> {
   assertOrder(query);
   const where = jobWhere(query.where ?? []);
   if (where.empty) return [];
-  const { introspect } = jobsOperator();
-  const records = await introspect.list({
-    ...where.filter,
-    // The admin asks one row past its page to learn whether there is a next one; the store's page
-    // is bounded, and a full store page simply reads as "maybe more".
-    limit: Math.min(query.limit, MAX_JOB_PAGE),
-    ...(query.after === undefined ? {} : { after: cursorOf(query.after) }),
-    ...(query.before === undefined ? {} : { before: cursorOf(query.before) }),
-  });
+  const found = await records(where.filter, query);
   const exact = where.exactId;
-  return (exact === undefined ? records : records.filter((record) => record.id === exact)).map(
-    jobRow,
-  );
+  return (exact === undefined ? found : found.filter((record) => record.id === exact)).map(jobRow);
 }
 
 /** The detail: the row, plus what `inspectJob` says of it — redacted input, steps, the stack. */

package/src/jobs/operator.ts

@@ -2,11 +2,11 @@
 // boot installs it after `defineAdmin()` has run, and `x dev` swaps it — and its operator surface.
 // A process with no driver, or one that ships no operator surface, is refused with the fix.
 
+import { NotImplementedError } from '@ultimat3/core';
 import {
   DriverUnavailableError,
   type JobDriver,
   type JobIntrospection,
-  JobsNotImplementedError,
   jobDriver,
 } from '@ultimat3/jobs';
 
@@ -25,8 +25,8 @@ export function jobsOperator(): JobsOperator {
     });
   }
   if (driver.introspect === undefined) {
-    throw new JobsNotImplementedError({
-      feature: `the operator surface of the "${driver.name}" jobs driver`,
+    throw new NotImplementedError({
+      cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
       fix: 'call setJobDriver(createPgDriver()) at boot — the pg and memory drivers implement introspect',
     });
   }

package/src/keyset-seek.ts

@@ -0,0 +1,189 @@
+// The keyset seek on the PAIR `(sort, id)`, for a typed handle whose chain is a conjunction: the
+// row-value comparison `(sort, id) > (v, id₀)` is read as disjoint segments in walk order — the
+// rest of the boundary's class by id, then everything past the class, then the NULLs — so a sort
+// value shared by any number of rows, and a NULL one, is a position like any other.
+
+import type { AdminListQuery, AdminRow, AdminTableRead, KeysetBound } from './registry';
+
+type TableOperator = Parameters<AdminTableRead['andWhere']>[1];
+type Direction = 'asc' | 'desc';
+
+/** One `andWhere` term. `value` is absent for the two null tests. */
+export interface SeekTerm {
+  readonly field: string;
+  readonly op: TableOperator;
+  readonly value?: unknown;
+}
+
+export interface SeekColumn {
+  readonly field: string;
+  readonly idField: string;
+  readonly nullable: boolean;
+  /**
+   * A `timestamptz`. The row hands it back as a `Date` — milliseconds — while Postgres keeps and
+   * orders microseconds, so a cursor can only name the boundary's MILLISECOND. Its class is that
+   * millisecond `[v, v + 1ms)`, ordered by id inside: the order both drivers can agree on.
+   */
+  readonly instant: boolean;
+  /** The bound's text back to what the handle compares: a `Date` for an instant. */
+  readonly typed: (value: string) => unknown;
+}
+
+const flip = (direction: Direction): Direction => (direction === 'asc' ? 'desc' : 'asc');
+
+const millisOf = (row: AdminRow, field: string): number | null => {
+  const value = row[field];
+  return value instanceof Date ? value.getTime() : null;
+};
+
+/** Where one walk segment reads. */
+interface Segments {
+  readonly read: (
+    where: readonly SeekTerm[],
+    order: 'id' | 'pair',
+    limit: number,
+  ) => Promise<AdminRow[]>;
+  readonly column: SeekColumn;
+  readonly walk: Direction;
+}
+
+/** The terms that hold the boundary's class: equal, the same millisecond, or NULL. */
+const classOf = (column: SeekColumn, value: unknown): readonly SeekTerm[] => {
+  if (value === null) return [{ field: column.field, op: 'is-null' }];
+  if (column.instant && value instanceof Date) {
+    return [
+      { field: column.field, op: 'gte', value },
+      { field: column.field, op: 'lt', value: new Date(value.getTime() + 1) },
+    ];
+  }
+  return [{ field: column.field, op: 'eq', value }];
+};
+
+/** Strictly past the class of a present `value`, in the walk's direction. NULLs never match. */
+const pastClass = (column: SeekColumn, value: unknown, walk: Direction): readonly SeekTerm[] => {
+  if (walk === 'desc') return [{ field: column.field, op: 'lt', value }];
+  if (column.instant && value instanceof Date) {
+    return [{ field: column.field, op: 'gte', value: new Date(value.getTime() + 1) }];
+  }
+  return [{ field: column.field, op: 'gt', value }];
+};
+
+/** One class, by id, after `afterId` when given — exact whatever the class's internal order. */
+const classRows = (
+  at: Segments,
+  where: readonly SeekTerm[],
+  afterId: string | undefined,
+  limit: number,
+): Promise<AdminRow[]> =>
+  limit <= 0
+    ? Promise.resolve([])
+    : at.read(
+        afterId === undefined
+          ? where
+          : [
+              ...where,
+              { field: at.column.idField, op: at.walk === 'asc' ? 'gt' : 'lt', value: afterId },
+            ],
+        'id',
+        limit,
+      );
+
+/**
+ * Present values past `where`, `limit` of them in `(sort, id)` order. For an instant the LAST
+ * millisecond read may be cut part-way through and its rows are in microsecond order, so it is
+ * dropped and re-read whole by id — the order the next page's seek resumes in. Every earlier
+ * millisecond on the page is complete, and is put in that same order.
+ */
+async function valueRows(
+  at: Segments,
+  where: readonly SeekTerm[],
+  limit: number,
+): Promise<AdminRow[]> {
+  if (limit <= 0) return [];
+  const { column } = at;
+  const present: readonly SeekTerm[] =
+    where.length === 0 && column.nullable ? [{ field: column.field, op: 'is-not-null' }] : where;
+  if (!column.instant) return at.read(present, 'pair', limit);
+  const rows = await at.read(present, 'pair', limit + 1);
+  if (rows.length <= limit) return byMillisecondThenId(rows, column, at.walk);
+  const tail = millisOf(rows[limit - 1] ?? {}, column.field);
+  const extra = millisOf(rows[limit] ?? {}, column.field);
+  const kept = rows.slice(0, limit);
+  if (tail === null || tail !== extra) return byMillisecondThenId(kept, column, at.walk);
+  const whole = kept.filter((row) => millisOf(row, column.field) !== tail);
+  const rest = await classRows(
+    at,
+    classOf(column, new Date(tail)),
+    undefined,
+    limit - whole.length,
+  );
+  return [...byMillisecondThenId(whole, column, at.walk), ...rest];
+}
+
+/**
+ * Rows of one millisecond in id order. Code-unit order: it agrees with the database for a `uuid`
+ * key, which is the framework's; a text key under a non-C collation can disagree inside one
+ * millisecond, and only there.
+ */
+const byMillisecondThenId = (
+  rows: readonly AdminRow[],
+  column: SeekColumn,
+  walk: Direction,
+): AdminRow[] => {
+  const sign = walk === 'asc' ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const at = (millisOf(a, column.field) ?? 0) - (millisOf(b, column.field) ?? 0);
+    if (at !== 0) return sign * at;
+    const left = String(a[column.idField]);
+    const right = String(b[column.idField]);
+    return sign * (left < right ? -1 : left > right ? 1 : 0);
+  });
+};
+
+/**
+ * The page a query asks for, read in WALK order — forward from an `after` bound (or from the top),
+ * backward from a `before` one — and answered in the query's own sort order either way.
+ *
+ * NULL is the largest value, as both drivers order it: last ascending, first descending.
+ */
+export async function seekPage(
+  query: AdminListQuery,
+  column: SeekColumn,
+  read: (
+    where: readonly SeekTerm[],
+    order: { readonly by: 'id' | 'pair'; readonly direction: Direction },
+    limit: number,
+  ) => Promise<AdminRow[]>,
+): Promise<readonly AdminRow[]> {
+  const backward = query.before !== undefined;
+  const walk = backward ? flip(query.sort.direction) : query.sort.direction;
+  const at: Segments = {
+    column,
+    walk,
+    read: (where, by, limit) => read(where, { by, direction: walk }, limit),
+  };
+  const out: AdminRow[] = [];
+  const room = (): number => query.limit - out.length;
+  const bound: KeysetBound | undefined = query.after ?? query.before;
+  const nulls = (afterId?: string): Promise<AdminRow[]> =>
+    column.nullable ? classRows(at, classOf(column, null), afterId, room()) : Promise.resolve([]);
+
+  if (bound === undefined) {
+    if (walk === 'desc') out.push(...(await nulls()));
+    out.push(...(await valueRows(at, [], room())));
+    if (walk === 'asc') out.push(...(await nulls()));
+  } else if (bound.value === null) {
+    out.push(...(await nulls(bound.id)));
+    if (walk === 'desc') out.push(...(await valueRows(at, [], room())));
+  } else {
+    const value = column.typed(bound.value);
+    // The id IS the sort: its class is one row, so only the strict half is read.
+    if (column.field !== column.idField) {
+      out.push(...(await classRows(at, classOf(column, value), bound.id, room())));
+    }
+    out.push(...(await valueRows(at, pastClass(column, value, walk), room())));
+    if (walk === 'asc') out.push(...(await nulls()));
+  }
+  const page = out.slice(0, query.limit);
+  return backward ? page.reverse() : page;
+}

package/src/list-filters.ts

@@ -61,12 +61,32 @@ const LOCAL_MINUTE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
 /** An instant names its offset. A bare local time has no zone, and the admin never invents one. */
 const ZONED = /(?:Z|[+-]\d{2}:\d{2})$/;
 
+/**
+ * A number as an operator types one: decimal digits, a sign, a point. `Number()` alone read a
+ * blank as `0`, `0x10` as 16 and `1e3` as 1000 — a filter nobody asked for, answered as a list.
+ */
+const DECIMAL = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * The `YYYY-MM-DD` a value opens with names a day the calendar HAS. `Date` rolls `2026-02-30`
+ * over to March 2nd without a word, so the shape test passed and the driver was handed a day
+ * nobody typed.
+ */
+const onCalendar = (raw: string): boolean => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (month < 1 || month > 12 || day < 1) return false;
+  return day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+};
+
 /**
  * A typed instant → the ISO string a driver compares. `datetime-local` posts `YYYY-MM-DDTHH:mm`
  * and the control says UTC beside the box — the same contract the edit form states — and a bare
  * date is that day's first instant in UTC.
  */
 const instantOf = (raw: string): string | undefined => {
+  if (!onCalendar(raw)) return undefined;
   const text = DATE.test(raw)
     ? `${raw}T00:00:00.000Z`
     : LOCAL_MINUTE.test(raw)
@@ -92,14 +112,19 @@ function scalarOf(field: AdminField, raw: unknown): Scalar | Refusal {
     }
     case 'range': {
       if (field.type === 'number') {
-        const parsed = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : NaN;
-        return raw !== '' && Number.isFinite(parsed)
-          ? parsed
-          : { cause: `takes a number, got ${shown(raw)}` };
+        const parsed =
+          typeof raw === 'number'
+            ? raw
+            : typeof raw === 'string' && DECIMAL.test(raw)
+              ? Number(raw)
+              : NaN;
+        return Number.isFinite(parsed) ? parsed : { cause: `takes a number, got ${shown(raw)}` };
       }
       if (typeof raw !== 'string') return { cause: `takes a date as text, got ${shown(raw)}` };
       if (field.type === 'date') {
-        return DATE.test(raw) ? raw : { cause: `takes a YYYY-MM-DD date, got ${shown(raw)}` };
+        return DATE.test(raw) && onCalendar(raw)
+          ? raw
+          : { cause: `takes a YYYY-MM-DD date, got ${shown(raw)}` };
       }
       return (
         instantOf(raw) ?? {

package/src/list-request.ts

@@ -6,7 +6,7 @@
 //
 //   ?cursor=<signed>            keyset position (pagination.ts)
 //   ?sort=<field>:<asc|desc>    a sortable field; the direction defaults to desc
-//   ?scope=<name>               a declared scope; absent is the resource's default
+//   ?scope=<name>               a declared scope; absent is the resource's default, `*` is none
 //   ?f.<field>=<value>          a filter, by the field's default operator
 //   ?f.<field>.<op>=<value>     a filter, by a named operator; repeat the parameter for `in`
 //
@@ -18,6 +18,7 @@ import type { AdminListRequest } from './list-scope';
 import { scopeNamed } from './list-scope';
 import type { AdminFilter, AdminSort } from './registry';
 import type { AdminResource } from './resource';
+import { NO_SCOPE } from './resource-list';
 
 export const CURSOR_PARAM = 'cursor';
 export const SORT_PARAM = 'sort';
@@ -61,7 +62,7 @@ export function pageRequestOf(resource: AdminResource, url: URL): AdminListReque
   const filters: AdminFilter[] = [];
   let cursor: string | undefined;
   let sort: AdminSort | undefined;
-  let scope: string | undefined;
+  let scope: string | null | undefined;
 
   for (const key of new Set(url.searchParams.keys())) {
     const values = url.searchParams.getAll(key).filter((value) => value !== '');
@@ -70,7 +71,8 @@ export function pageRequestOf(resource: AdminResource, url: URL): AdminListReque
     if (key === CURSOR_PARAM) cursor = last;
     else if (key === SORT_PARAM) sort = sortOf(resource, last);
     // Resolved here for its refusal alone: the name is what travels, the actor decides its rows.
-    else if (key === SCOPE_PARAM) scope = scopeNamed(resource, last)?.name;
+    else if (key === SCOPE_PARAM)
+      scope = last === NO_SCOPE ? null : scopeNamed(resource, last)?.name;
     else if (key.startsWith(FILTER_PREFIX)) {
       filters.push(checkedFilter(resource, { ...filterKey(key), value: values }));
     } else {
@@ -108,9 +110,9 @@ export function listHref(
   location: ListLocation = {},
 ): string {
   const query = new URLSearchParams();
-  if (location.scope !== undefined && location.scope !== null) {
-    query.set(SCOPE_PARAM, location.scope);
-  }
+  // `null` is "no scope, not even the default" — the request's own meaning of it — so it is
+  // written, as `*`; only an absent scope is left to the resource's default.
+  if (location.scope !== undefined) query.set(SCOPE_PARAM, location.scope ?? NO_SCOPE);
   for (const filter of location.filters ?? []) {
     const field = resource.filters.find((known) => known.name === filter.field);
     if (field === undefined) continue;

package/src/mcp.ts

@@ -234,6 +234,10 @@ 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);
 }
 

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

@@ -23,9 +23,6 @@ import {
 } 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.
@@ -62,13 +59,18 @@ function readDecision(permission: string, result: unknown): AdminDecision {
 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 = (

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;
 }
 

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 };