@ultimat3/admin 23.0.0 → 25.0.0

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';
 
@@ -21,13 +21,13 @@ export function jobsOperator(): JobsOperator {
     throw new DriverUnavailableError({
       driver: 'none',
       cause: 'the jobs dashboard was asked for rows and this process installed no queue',
-      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: setJobDriver(createMemoryDriver())',
+      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: setJobDriver(memoryJobDriver())',
     });
   }
   if (driver.introspect === undefined) {
-    throw new JobsNotImplementedError({
-      feature: `the operator surface of the "${driver.name}" jobs driver`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — the pg and memory drivers implement introspect',
+    throw new NotImplementedError({
+      cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg and memory drivers implement introspect',
     });
   }
   return { driver, introspect: driver.introspect };

package/src/jobs/overview-tab.tsx

@@ -2,7 +2,7 @@
 // own queue (the dev driver under `x dev`) — one jobs UI, not a second one in the dev panel. Only
 // ever reached by `dev/panel-jobs.ts`'s dynamic `import()`, so `/_x`'s mount graph stays free of it.
 
-import { createContext, runWithContext } from '@ultimat3/core';
+import { ctxOf, runWithContext } from '@ultimat3/core';
 import { renderToHtml } from '@ultimat3/render/server';
 import { listHref } from '../list-request';
 import { adminMounts } from '../mounts';
@@ -33,7 +33,7 @@ export async function jobsTabHtml(tabPath: string, params: URLSearchParams): Pro
   const json = `${tabPath}?json=1`;
   const data = await overviewData(range, Date.now());
   // The framework catalog's locale for every label, whatever the app's default is.
-  return runWithContext(createContext({ locale: 'en', tz: 'UTC' }), () =>
+  return runWithContext(ctxOf({ locale: 'en', tz: 'UTC' }), () =>
     renderToHtml(
       <JobsOverview
         data={data}

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/layout.tsx

@@ -1,14 +1,18 @@
 // The admin shell: skip link, sidebar (brand, who is acting, search, permission-filtered nav, the
 // way back to the app), main region. Landmarks and a visible focus order are the accessibility
 // contract; the theme attributes come from the token system, so nothing here knows a colour.
-// Every control is a link or a native form — the shell ships no script.
+// Every control is a link, a native form or a native popover — the shell ships no script: below
+// `md` the sidebar is a `popover` panel the menu button opens by `popovertarget`, and an engine
+// with no popovers keeps it as a block above the screen (`admin.module.scss`).
 
 // why: `*.module.scss` is typed by ONE ambient declaration, and it is `@ultimat3/ui`'s. A copy
 // here would be a `.d.ts` in `src/`, which the package-shape gate reads as a build artifact.
 /// <reference path="../../ui/src/scss.d.ts" />
 
 import { t } from '@ultimat3/i18n';
-import { Input } from '@ultimat3/ui';
+import { Icon, Input, UI_KEYS } from '@ultimat3/ui';
+import { iconMenu } from '@ultimat3/ui/icons/menu';
+import { iconX } from '@ultimat3/ui/icons/x';
 import type { JSX } from 'solid-js';
 import type { AdminApp } from './admin';
 import styles from './admin.module.scss';
@@ -27,8 +31,11 @@ export interface AdminLayoutProps {
   readonly children: JSX.Element;
 }
 
+/** The panel's id: the menu button and the close button both name it. */
+const SIDE_ID = 'x-admin-side';
+
 /** The one rendering of "who am I acting as", so no two screens can disagree about it. */
-export const actorLabel = (actor: AdminActor | null | undefined): string =>
+export const adminActorLabel = (actor: AdminActor | null | undefined): string =>
   actor === null || actor === undefined || actor.id === 'anonymous'
     ? t('admin.actor.anonymous')
     : t('admin.actor.signedIn', { id: actor.id, roles: (actor.roles ?? []).join(', ') });
@@ -44,10 +51,29 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
       data-density={theme['data-density']}
       style={theme.style}
     >
-      <aside class={styles['side']}>
-        <a class={styles['skip']} href="#x-admin-main">
-          {t('admin.a11y.skip-to-content')}
-        </a>
+      {/* Ahead of the panel, not inside it: a closed panel is `display: none`, and so would be
+          the first Tab stop on every admin screen. */}
+      <a class={styles['skip']} href="#x-admin-main">
+        {t('admin.a11y.skip-to-content')}
+      </a>
+
+      <div class={styles['bar']}>
+        <button type="button" class={styles['menuButton']} popovertarget={SIDE_ID}>
+          <Icon glyph={iconMenu} size="md" />
+          {t(UI_KEYS.menu)}
+        </button>
+      </div>
+
+      <aside id={SIDE_ID} class={styles['side']} popover="auto">
+        <button
+          type="button"
+          class={styles['close']}
+          popovertarget={SIDE_ID}
+          popovertargetaction="hide"
+          aria-label={t(UI_KEYS.close)}
+        >
+          <Icon glyph={iconX} size="md" />
+        </button>
 
         <a class={styles['brand']} href={base}>
           {props.app.branding.logo === undefined ? null : (
@@ -59,7 +85,7 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           )}
           <span>{t(props.app.branding.nameKey)}</span>
         </a>
-        <p class={styles['actor']}>{actorLabel(props.actor)}</p>
+        <p class={styles['actor']}>{adminActorLabel(props.actor)}</p>
 
         {/* A native GET at the search route: the term rides the URL, so a result page is a link
             an operator can send and the form needs no handler. */}

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/list.tsx

@@ -139,7 +139,7 @@ export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX
           rows={page.rows}
           rowKey={idOf}
           sort={{ key: page.sort.field, direction: page.sort.direction }}
-          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          nextCursor={page.hasMore ? page.nextCursor : undefined}
           prevCursor={page.prevCursor ?? undefined}
           hrefFor={(cursor) => props.hrefFor({ ...state, cursor })}
           // The header's NEXT state, as a URL. "Unsorted" is the list with no sort in it — the

package/src/mcp-scopes.ts

@@ -0,0 +1,36 @@
+// The admin MCP surface's scopes: which admin permission each tool needs as a token scope, and
+// what a resolved token carries. The gate itself is `@ultimat3/mcp`'s registry — this file only
+// declares the cut (`defineAppMcp({ scopes })`) and the token's half of it.
+
+import type { McpScopes } from '@ultimat3/mcp';
+import { expandPermissions } from './authz';
+import type { AdminMcpTool } from './mcp-tools';
+import { ADMIN_DESTROY, ADMIN_PERMISSIONS } from './permissions';
+
+const isAdminPermission = (scope: string): boolean =>
+  (ADMIN_PERMISSIONS as readonly string[]).includes(scope);
+
+/**
+ * The scopes a token resolved to, as the registry checks them: by string membership, so the
+ * admin's implications are expanded here (`admin:destroy` ⇒ `admin:write` ⇒ `admin:read`) and a
+ * token granted `admin:write` is not refused a read.
+ *
+ * `undefined` — the app's resolver stated no scopes — is a token as strong as its actor: every
+ * admin scope, with the actor's own policy still deciding each tool. That is what every admin MCP
+ * token was before tools carried a scope, so an app that never issued a narrower token is
+ * unchanged. An EMPTY list is a token granted nothing, never "unstated". A scope that is no admin
+ * permission (`posts:write`) is dropped: the admin's tools are gated on its own vocabulary only.
+ */
+export function adminTokenScopes(granted: readonly string[] | undefined): ReadonlySet<string> {
+  return new Set(expandPermissions(granted ?? [ADMIN_DESTROY]).filter(isAdminPermission));
+}
+
+/**
+ * Scope → the tools it covers, for `defineAppMcp({ scopes })`. Every tool is in exactly one entry
+ * (its `scope`), so the map is total by construction and `X_MCP_SCOPE_UNCOVERED` cannot fire.
+ */
+export function adminToolScopes(tools: readonly AdminMcpTool[]): McpScopes {
+  const by = new Map<string, string[]>();
+  for (const tool of tools) by.set(tool.scope, [...(by.get(tool.scope) ?? []), tool.name]);
+  return Object.fromEntries(by);
+}

package/src/mcp-tools.ts

@@ -5,12 +5,12 @@
 // Tool descriptions are literal English on purpose: they are protocol payload read by a
 // model, not UI copy read by a person, so they are not `t()` keys.
 
-import { decideAction, permissionsForAction } from './action-gate';
+import { adminPermissionForAction, decideAction, permissionsForAction } from './action-gate';
 import type { AdminApp } from './admin';
 import { type AdminDecision, decideAll } from './authz';
 import { type CrudCtx, decideOperation, permissionsForOperation } from './crud';
 import type { AdminFieldType } from './fields';
-import type { AdminOperation } from './permissions';
+import { type AdminOperation, type AdminPermission, adminPermissionFor } from './permissions';
 import type { AdminAction } from './registry';
 import type { AdminResource } from './resource';
 
@@ -32,6 +32,12 @@ export interface AdminMcpTool {
   readonly entity: string | null;
   readonly action: string | null;
   readonly permissions: readonly string[];
+  /**
+   * The MCP scope a token must carry to call it: the admin-level permission it needs — `admin:read`
+   * for a read and a `readonly` action, `admin:write` for a write, `admin:destroy` for a delete or a
+   * destructive action. The connection's gate, checked before the actor's own policy.
+   */
+  readonly scope: AdminPermission;
   /** Destructive tools require the confirmation token; agents must read before they delete. */
   readonly destructive: boolean;
   readonly input: readonly AdminToolField[];
@@ -110,6 +116,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         entity: resource.name,
         action: null,
         permissions: permissionsForOperation(resource.permission, 'list'),
+        scope: adminPermissionFor('list'),
         destructive: false,
         input: [
           CURSOR_FIELD,
@@ -126,6 +133,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         entity: resource.name,
         action: null,
         permissions: permissionsForOperation(resource.permission, 'detail'),
+        scope: adminPermissionFor('detail'),
         destructive: false,
         input: [ID_FIELD],
       };
@@ -137,6 +145,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         entity: resource.name,
         action: null,
         permissions: permissionsForOperation(resource.permission, 'create'),
+        scope: adminPermissionFor('create'),
         destructive: false,
         input: formFields(resource),
       };
@@ -148,6 +157,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         entity: resource.name,
         action: null,
         permissions: permissionsForOperation(resource.permission, 'update'),
+        scope: adminPermissionFor('update'),
         destructive: false,
         input: [ID_FIELD, ...formFields(resource)],
       };
@@ -159,6 +169,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         entity: resource.name,
         action: null,
         permissions: permissionsForOperation(resource.permission, 'delete'),
+        scope: adminPermissionFor('delete'),
         destructive: true,
         input: [ID_FIELD, { name: 'confirmation', type: 'text', required: true }],
       };
@@ -202,6 +213,7 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
           entity: action.entity ?? null,
           action: action.name,
           permissions: permissionsForAction(action),
+          scope: adminPermissionForAction(action),
           destructive: action.destructive === true,
           input: actionEnvelope(action),
         },
@@ -220,6 +232,7 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
       entity: null,
       action: null,
       permissions: permissionsForOperation('admin', 'search'),
+      scope: adminPermissionFor('search'),
       destructive: false,
       input: [{ name: 'term', type: 'text', required: true }],
     },
@@ -237,6 +250,7 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
         entity: null,
         action: action.name,
         permissions: permissionsForAction(action),
+        scope: adminPermissionForAction(action),
         destructive: action.destructive === true,
         input: actionEnvelope(action),
       },