@ultimat3/admin 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **No screen ships a script.** Every route is `ssr` + `hydrate: 'never'`, so a control is a link or a native form: `<Pagination hrefFor>`, `<DataTable sortHrefFor>`, scope tabs as links, the filter bar one GET form, a form posted at the URL that rendered it, an action posted at its ROW's URL (`_operation`). `form-decode.ts` is the one place posted strings become typed input, per widget — an empty box of a typed widget (money, number, instant, JSON) is `null`, never `''`.
 - **A list's state is its URL, and a parameter the resource does not derive is REFUSED.** `list-request.ts` is the one parser and builder — `?cursor=`, `?sort=<field>:<asc|desc>`, `?scope=<name>` (`*` = none, not even the default; undeclarable), `?f.<field>[.<op>]=<value>` (repeat for `in`; empty = absent). `list-filters.ts` owns the operators per filter shape and the ONE validator (`checkedFilter`) the URL and the MCP list tool's `where` both pass. Unknown field, operator, sort, scope or parameter, or a value that is not the column's type: `X_ADMIN_FILTER_INVALID`, a 400 naming what the list answers — never the unfiltered list.
 - **One composition of predicates** (`list-scope.ts`): row scope (`rows`), then scope, then filters. Every read of a resource builds its `where` there, and every read of ONE row is `findRow` — never `repo.find` from a screen, `crud.ts` or `mcp.ts` — so a row outside `rows(actor)` is "not found" on list, search, detail, edit, action, lookup, labels and MCP alike (`row-scope.test.ts`). App-declared predicates (`scopes`, `rows`) pass `declaredFilters`: any column, never a sealed one.
-- **A widget never reads a row.** What a page shows of the resources it references is read ONCE per target by `relations.ts` (`relationsFor`: one statement, two for a picked target over `LOOKUP_SELECT_MAX`) and handed down as `WidgetContext.labelFor` / `optionsFor` / `lookupHref`. A target the actor may not list is an id with no name. `list-relations.test.ts` asserts the statement count at the driver. The picker is server-rendered: a `<select>` for a small target, else an id box + the target's lookup screen (`/admin/<resource>/lookup`, `screen-lookup.tsx`, `return` held to the admin's own paths).
+- **A widget never reads a row.** What a page shows of the resources it references is read ONCE per target by `relations.ts` (`relationDataFor`: one statement, two for a picked target over `LOOKUP_SELECT_MAX`) and handed down as `WidgetContext.labelFor` / `optionsFor` / `lookupHref`. A target the actor may not list is an id with no name. `list-relations.test.ts` asserts the statement count at the driver. The picker is server-rendered: a `<select>` for a small target, else an id box + the target's lookup screen (`/admin/<resource>/lookup`, `screen-lookup.tsx`, `return` held to the admin's own paths).
 - **A sealed column is never a filter, a scope or row-scope predicate, a label, a lookup key or a computed column's input** — `.sealed({ lookup: true })` included: a filter value rides a URL, and a URL is logged. `computedRow` drops sealed names from the row a column's `value` is handed.
 - **The tenant column is the handle's, never an input** (`crud-input.ts`): not a form field, a list column or a filter; a create is stamped with the ACTOR's tenant and a patch never carries the column.
 - **Computed columns are a closed renderer set** (`renderers.tsx`: `badge`, `relative-time`, `money`, `truncate`, `link`, `json`) or a component; `AdminComputedColumn` is typed over `AdminRow` so a resource stays covariant in `Row`.
@@ -26,13 +26,13 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **One `AdminAction.name`, one handler** — the MCP tool name, the default label key and `callAdminTool`'s lookup. A duplicate is `X_ADMIN_ACTION_DUPLICATE` at `defineAdmin`; identity, not name, is what "already seen" means.
 - **A `/_x` source reads a registry through its DESCRIPTOR TYPE, never as an untyped bag** — `import type { RouteDescriptor }` beside the dynamic `import()`; `dev/published-keys.test.ts` walks what the registries EMIT. A route fact carries `mount` (`{ by, permissions }` or `null`).
 - **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
-- **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describeRoutes()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
+- **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describePages()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
 - **The admin's stylesheets are claimed for `app/`** (`stylesheet-scope.ts`, `claimStylesheets`). `stylesheet-scope.test.ts`.
 - **Importing this package declares NO permission.** `defineAdmin()` calls `declareAdminPermissions`, which registers `ADMIN_PERMISSIONS` plus what the mount derives (`policy-bridge.test.ts`).
-- **One bridge per foreign package.** `policy-bridge.ts` is the only file calling `evaluate`/`definePermissions`; `route-config.ts` the only one calling `defineRoute`/`registerMountedRoutes`; `mcp.ts` the only one calling `defineAppMcp`; `dev/data.ts` the only one importing introspection (dynamically — `/_x` must stay out of the production graph). Source only: a **test** declares the permissions its own `can()` fixtures use, and calls `defineAdmin()` in `beforeAll`, NEVER at module scope — the leak guard keeps what a file's module scope registered for every later file, so one module-scope admin closed the permission set for `bun test packages/admin packages/query`.
+- **One bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes`; `mcp.ts` → `defineAppMcp`; `dev/data.ts` → introspection, dynamically. A test declares its own fixtures' permissions and calls `defineAdmin()` in `beforeAll`, never at module scope.
 - **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
 - **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
-- **A deliberate query loop declares itself.** `search.ts` runs one indexed lookup per text field on purpose — the query IR is a conjunction, so three small indexed reads beat one unindexed `OR` — and says so through `expectedQueryLoop()` from `@ultimat3/db` — as do `batch.ts` (one row at a time) and `relations.ts` (label reads chunked at 200 ids, never cut). That is the one suppression mechanism: never a comment pragma and never a list of exempt call sites. A new loop here either argues for itself in a `reason` or it is an N+1.
+- **A deliberate query loop declares itself** — `expectedQueryLoop()` from `@ultimat3/db`, with a `reason` (`search.ts`, `batch.ts`, `relations.ts`). Never a comment pragma, never an exempt list; an undeclared loop is an N+1.
 - **The timeline panel renders the detector's verdicts** (`DevSources.statementLoops()`), never a second count; none wired is `null`, never `[]`.
 - **This catalog is the framework's one opt-OUT MCP surface, deliberately**: `mcp-tools.ts` does not call `isMcpExposed` — every tool is already gated on an admin permission. `mcp: { expose: false }` withdraws one. A *second* exception anywhere is the bug.
 - **`dev/panel-db.ts`'s `sanitize` decides "did they type a statement", not "is it safe"** — never cite it as a security property.
@@ -48,29 +48,32 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **A table read by a runtime key is `Object.hasOwn` / a `Map`, never a bare index** — `impliedBy`, the `/_x` counters, `list-filters.ts`' operator table, `renderers.tsx` (`bun run proto-index`).
 - **The `/_x` SQL runs in `readOnlyQuery`** (`dev/sql-runner.ts`, `readOnlySql(client)` — what a host wires as `runSql`): read-only transaction, timeout, `DEV_SQL_MAX_ROWS`.
 - **One read-only SQL guard, and it is `@ultimat3/mcp`'s** — no local keyword scan; the panel keeps only the emptiness test and the way out (`psql "$DATABASE_URL"`, the developer's own client — `x db` has no `psql`).
-- **Every admin operation is audited, reads included.** `ListResult` carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`). `AdminSearchResult.audit` carries one entry per resource it decided about — `allowed` per searched resource, a `deniedDraft` per refused one; a resource skipped for no text field, no repo or a repo that THREW (`admin.search.skipped.failed`) is listed in `skipped`, never a 500 for the rest.
+- **Every admin operation is audited, reads included**, not `/admin`'s counts (a count reads no row). `ListResult` carries its `AuditEntry` on both branches (`entityId: null`); `AdminSearchResult.audit` one entry per resource decided, and a skipped resource (no text field, no repo, a repo that threw) is in `skipped`, never a 500.
 - **A write's RESULT satisfies the actor's row scope** (`row-scope-write.ts`): a create, and an update over the fields it touches, outside `rows(actor)` is refused before the repo — `admin.error.row-out-of-scope`, audited as a denial. The one predicate evaluator in this package; an ordering over text is refused, never guessed. `row-scope-write.test.ts`.
 - **An action's `when(row)` is asked by the button AND by the call** (`actionApplies`, `action-gate.ts`): a row it excludes is `X_ADMIN_ACTION_NOT_APPLICABLE` (409 on a screen, the code over MCP), audited `admin.error.action-not-applicable`. The row it reads carries no sealed column. Every action on one row runs through `invokeRowAction` (`findRow` first).
 - **An action with an `input` schema is a form, never a bare post**: its button links to `<row>?action=<name>`, the form posts `input.<field>` (`action-input.ts`, through `tryIntrospect`), the gate validates against the schema and a refusal is a 422 with issues on their fields. No schema: a confirm only.
-- **A batch is the button's gate once per row** (`batch.ts`): policy, `when`, handler; counts `done`/`refused`/`failed`/`queued`/`remaining`; one audit entry per row. Selection is checked ids or "all matching" — the list URL's own `listWhere`, keyset by id, `MAX_BATCH_ROWS` inline / `MAX_BATCH_QUEUED_ROWS` queued per request. `batch: { threshold }` queues one `admin.batch` job per chunk (`batch-queue.ts`, `batch-job.ts`) under a DERIVED `batchIdOf` (actor, action, rows, input — not the request id), so a retry dedupes; the worker runs it AS the operator. Zero JS: the bar is one form (`batch-bar.tsx`), row checkboxes join it by `form=`; a destructive or input-taking batch is a server round trip. ONE MCP tool per action — a batch action's tool takes `ids`.
+- **A batch is the button's gate once per row** (`batch.ts`): policy, `when`, handler, one audit entry each. Checked ids or "all matching" (`listWhere`, keyset by id, `MAX_BATCH_ROWS` / `MAX_BATCH_QUEUED_ROWS`). `batch: { threshold }` queues `admin.batch` jobs under a derived `batchIdOf`, run AS the operator. Zero JS (`batch-bar.tsx`). ONE MCP tool per action — a batch action's tool takes `ids`.
 - **Sections and form groups never hide a field** (`resource-layout.ts`): undeclared fields fall into a default group drawn last; a name that is not a drawn field, or claimed twice, is refused at `defineAdmin`. `on: 'create' | 'update'` is enforced on the write too (`onlyFor`, `crud-input.ts`).
 - **A related list IS the related resource's list** (`related.ts`): a `hasMany` of the entity, read through `adminList` (its gate, its `rows`), filtered to this row; a resource the actor may not list is left out. One label read per target for the whole detail page.
 - **The audit log is the store, a sink is a copy.** `AuditLog.entries()` is async, keyset (`before`), `changes: true` drops allowed reads; `atomic(run)` puts a write and its entry in one transaction (`auditedWrite`). `postgresAuditLog()` writes `x_admin_audit` (`audit-pg.ts`), skips allowed reads unless `reads: true`. `audit-pg.contract.test.ts` boots PGlite.
-- **The jobs dashboard is every admin's, built from these pieces only** (`jobs/`): four resources — `x_jobs`, `x_job_queues`, `x_job_tasks`, `x_job_workers` — each with a `repo:` over `JobIntrospection` (`job-repo.ts`, `fleet-repo.ts`), scopes, a row scope and `job-actions.ts`'s `AdminAction`s, plus ONE screen (`overview.tsx`, the view `jobs`). `job:read` lists them (the resources' `permission` noun is `job`), `job:manage` runs every action. An actor with an `orgId` sees that org's job rows and none of the fleet. `jobs/boundary.test.ts` refuses a `fetch(`, a socket, an event stream or a hand-written table there; `/_x/jobs` draws `JobsOverview` over the dev queue (`dev/panel-jobs.ts` → `jobs/overview-tab.tsx`, dynamically).
+- **The jobs dashboard is every admin's, built from these pieces only** (`jobs/`): resources `x_jobs`, `x_job_queues`, `x_job_tasks`, `x_job_workers` with `repo:`s over `JobIntrospection`, scopes, a row scope and `job-actions.ts`, plus ONE screen (`overview.tsx`). `job:read` lists, `job:manage` acts; an `orgId` actor sees its org's jobs and none of the fleet. `jobs/boundary.test.ts`.
 - **A job-store predicate the store cannot answer is refused by name** (`job-where.ts`, `X_ADMIN_FILTER_INVALID`): one order (`createdAt desc`), equality on state/queue/name/tenant, an id PREFIX for the id box. `listScreen` answers a repo's refusal 400, as the URL's. "All matching" over jobs is `AdminAction.matching` onto the store's bulk verbs, never a walk.
 - **A resource's permissions are named after its `permission` noun** (`resource.permission`, default the entity name) — every `permissionsForOperation` site reads it, never `resource.name`.
+- **An action's admin gate is ONE function** (`adminPermissionForAction`, `action-gate.ts`): `destructive` → `admin:destroy`; `matching` → `admin:write`, `readonly` beside it or not — it changes every row the list matches; `readonly` → `admin:read`; else `admin:write`. A contradiction fails closed. The same value is its MCP tool's `scope`. `action-gate.test.ts`.
+- **Every admin MCP tool carries ONE scope** — `admin:read`, `admin:write` or `admin:destroy`, by what it does (`mcp-tools.ts`); `adminToolScopes` hands that cut to `defineAppMcp({ scopes })`. A token's own scopes are `AdminMcpActor.tokenScopes` (not `scopes`: core's `Actor.scopes` is another thing), expanded `destroy ⇒ write ⇒ read` by `adminTokenScopes` (`mcp-scopes.ts`). **Unstated = full strength** (the actor's); **`[]` = granted nothing**, every tool refused `X_MCP_SCOPE_DENIED`; a non-admin scope is dropped. The scope gate runs before the actor's policy, which still decides. `mcp-scopes.test.ts`.
+- **The `/admin` home counts only what opted in** — `count: true` on the resource (`screen-home-counts.ts`): one `count()` over `rowWhere(actor)` per visit, so it is never a default. Only resources the actor may list; a repo with no `count()`, or one that throws, has no tile — never a zero.
 - **`matching` is "all matching" as ONE call** (`batch-matching.ts`): the list's `where`, gated by the batch's grant, confirmed as `<entity>:all matching`, audited once (`admin.batch.matching`). A checked selection never reaches it.
 - **An action on a row the actor cannot see is refused, `when` or none** (`actionApplies`: a `null` row is no row).
 - **An action's input field is labelled `admin.input.<action>.<field>`** — never under `admin.action.<action>`, which is a leaf: a JSON catalog cannot hold both.
 - **`x_admin_audit`'s DDL is the leaf `audit-schema.ts`** (`@ultimat3/admin/schema`): the boot applies it in every role; `serve-graph.test.ts` exempts exactly that file.
-- Money through `assertMoney`, timestamps through `assertZone`, pagination through `pagination.ts`. No `offset`, ever.
+- Money via `assertMoney`, timestamps via `assertZone`, pagination via `pagination.ts`. No `offset`, ever.
 - **One cursor codec.** `pagination.ts` is the only file calling core's `encodeCursor`/`decodeCursor`; it wraps them as `encodeAdminCursor`/`decodeAdminCursor`, scoped `admin:<resource>`. An invalid cursor is page one here, not an error page — but the signature is checked first, so a forged one cannot seek.
 - Labels are i18n keys derived in `resource.ts` (`admin.<entity>.field.<name>`); only `.tsx` calls `t()`. An action's is `actionLabelKey` (`action-label.ts`), never respelled. `AdminApp.catalogKeys()` (`catalog-keys.ts`) is every derived key — the CLI's `i18n` step audits exactly that list. MCP tool descriptions are literal English (protocol payload, not UI copy).
 - Colours only via `ThemeTokenRef` (`--x-*`). Raw hex does not typecheck.
 - **One owner of `globalThis.React` is `@ultimat3/ui`'s** (`probe`/`unprobe`); `inert-jsx.ts` keeps only the walkers. `inert-jsx.test.ts` drives both install orders.
 - **A `/_x` panel orders by CODE UNIT, never `localeCompare`**; **the locale picker reads `registeredLocales()`**, never a bundled list.
-- Views are pure functions of props — no `createSignal`, no local state, no event handler.
-- **No test reaches a `.tsx` statically.** `routes.ts` reaches the screens, so a test does `await import('@ultimat3/render/server')` and then `await import('./routes')`: a static import compiles JSX before the loader exists and every later render dies with `React is not defined`.
+- Views are pure functions of props: no `createSignal`, local state or event handler.
+- **No test reaches a `.tsx` statically**: `await import('@ultimat3/render/server')`, then `await import('./routes')`.
 
 ## Layout
 
@@ -91,7 +94,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `batch.ts` / `batch-queue.ts` / `batch-bar.tsx` / `batch-job.ts` | a batch through the gate / its queued half / the bar and row checkboxes / the `admin.batch` job |
 | `resource-fields.ts` / `resource-layout.ts` / `related.ts` / `list-columns.tsx` | one column → one field / sections and form groups / related lists / a resource's table columns |
 | `audit.ts` / `audit-pg.ts` / `json-text.ts` | the log interface + memory log / the Postgres log / readable JSON for a cell or a diff |
-| `mcp-tools.ts` / `mcp.ts` | tool derivation (pure) / transport wiring |
+| `mcp-tools.ts` / `mcp-scopes.ts` / `mcp.ts` | tool derivation, each tool's scope (pure) / scope → tools for `defineAppMcp`, a token's expanded scopes / transport wiring |
 | `test-ctx.ts` | `adminTestCtx({ actor?, granted? })` — the `CrudCtx` a test hands a page or a CRUD call; `staticAuthz` over a grant list, its own audit log. What `x g admin:page`'s emitted render test calls |
 | `jobs/` | the jobs dashboard: entities, repos, the where translation, actions, labels, resources, the overview and its `/_x` tab |
 | `batch-matching.ts` / `audit-schema.ts` | a set-based "all matching" / the audit table's DDL, a leaf |

package/README.md

@@ -8,7 +8,7 @@
 | Audience | you, debugging the framework | your operators, and their agents |
 | Environment | development **only** — mounting it with `env=production` or `role=production` throws `X_DEV_DASHBOARD_IN_PROD` | production |
 | Authz | none: it is your own machine | the app's policies, one decision per surface |
-| Data | introspection calls (`describeRoutes`, `inspect`, `dependentsOf`, …) | the entity registry + repos |
+| Data | introspection calls (`describePages`, `inspect`, `dependentsOf`, …) | the entity registry + repos |
 | Shipped in the app image | never mounted | mounted at `/admin` |
 
 ## `/_x` panels
@@ -18,9 +18,9 @@ One panel per file. Each kills one question, and each is available as `--json`
 | Panel | Kills |
 |---|---|
 | `routes` | which handler serves this? — render mode, offline strategy, revalidate tags, budget |
-| `timeline` | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count |
+| `timeline` | where did the time go? — a server-rendered waterfall of SQL, cache, action, policy spans (one row per span, bar placed by the payload's own `offset`/`width`), time per kind, and the N+1 detector's verdicts with their fix lines; the payload folded under it |
 | `live` | what does each subscriber receive, and **why** — the matcher's decision trace |
-| `jobs` | the admin's own jobs overview (`/admin/jobs`'s component) over this process's queue; the payload — queue depth, step traces, retry-from-step target, dead letter — folded under it |
+| `jobs` | a ring of the recent runs by state (`DonutChart`), then the admin's own jobs overview (`/admin/jobs`'s component) over this process's queue; the payload — queue depth, step traces, retry-from-step target, dead letter — folded under it |
 | `db` | psql in a tab (read-only twice: `assertReadOnly` refuses DML, and `readOnlySql(client)` — what a host wires as `runSql` — runs it in a `BEGIN READ ONLY` transaction with a timeout and `DEV_SQL_MAX_ROWS`), schema + drift (`null` unless a host wires the check) |
 | `mail` | caught mail, rendered, per locale, with the locale gaps listed |
 | `cache` | the tag graph — what invalidated what, and which tags are orphans |
@@ -36,6 +36,8 @@ const authz = staticAuthz(['admin:read']);
 const actors = [{ id: 'dev-admin', roles: ['admin'] }];
 
 const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // throws in prod
+// A drawn tab renders ui's components; their rules are in the app surface's stylesheet, so a host
+// names its URL: devDashboard({ …, stylesheetHref: () => styleBundle().hrefFor('app') })
 const response = await dev.handle(request); // null when the path is not /_x
 await dev.json('jobs'); // the same payload /_x/jobs renders from
 ```
@@ -62,12 +64,22 @@ export const admin = defineAdmin({ entities: [posts, users], db });
 `/admin/posts/<id>`, `/admin/posts/<id>/edit`, plus `/admin/search`, `/admin/audit` and the jobs
 dashboard (`/admin/jobs`, below).
 
+`/admin` itself opens on a KPI row — one `StatTile` per resource the actor may list AND that
+declared `resources.<entity>.count: true`, its figure that resource's `AdminRepo.count()` over its
+`rows` scope, each tile a link to the list — and a `DonutChart` of the same counts, then the
+permission matrix per resource. Opt-in, as a scope tab's `count` is: a tile is one full `count()`
+per visit, so an operator reloading the front page over a big table is a load generator. A resource
+the actor may not list has no tile, no segment and no matrix; one that did not opt in, a repo with no
+`count()`, or one whose count the store refuses (`X_TENANCY_UNSCOPED` for an actor with no org), has
+no tile and never fails the page. A count reads no row, so it is not audited. Each matrix is a
+closed `<details>` whose summary reads "N of M allowed".
+
 | Input | What it is | Omitted |
 |---|---|---|
 | `entities` | the objects `entity()` returned — `adminEntitiesOf(db)` is every entity the handle serves | required |
 | `db` | the app's `database()` handle. Each resource reads through its own table: tenancy, soft delete, sealing and invariants are the handle's, and the admin adds no predicate | `resources.<entity>.repo` per resource, or `X_ADMIN_REPO_UNBOUND` at declaration |
-| `resources` | per-entity overrides — `listFields`, `labelField`, `columns`, `scopes`, `rows`, `sections`, `formGroups`, `related`, `fields.<name>.{sensitive,hintKey,on}`, `operations`, `repo`, `permission` (the noun its operations are named after; default the entity's name) | derived |
-| `actions` | `AdminAction[]` — a `permission` (never optional) plus a handler; optional `input` schema, `when(row)`, `batch` | none |
+| `resources` | per-entity overrides — `listFields`, `labelField`, `columns`, `scopes`, `count` (a tile on `/admin`), `rows`, `sections`, `formGroups`, `related`, `fields.<name>.{sensitive,hintKey,on}`, `operations`, `repo`, `permission` (the noun its operations are named after; default the entity's name) | derived |
+| `actions` | `AdminAction[]` — a `permission` (never optional) plus a handler; optional `input` schema, `when(row)`, `batch`, `readonly`, `destructive` | none |
 | `pages` | custom screens, see below | none |
 | `auth.actor` | who is acting | the actor the HTTP pipeline resolved for the request |
 | `auth.authz` | the one decision path | `roleAuthz()` — the role map decides each permission by name |
@@ -211,7 +223,8 @@ export const suspendUser: AdminAction = {
 | `batch` | the list's batch bar — checked rows, or every row the list's URL matches — each row through the button's gate and on the audit log, answered with `done` / `refused` / `failed` / `queued` / `remaining`. 200 rows inline per request (`MAX_BATCH_ROWS`), 1,000 queued (`MAX_BATCH_QUEUED_ROWS`); "all matching" continues from where it stopped |
 | `matching` | "all matching" as ONE set-based call: handed the list's `where` (row scope, scope, filters), it answers `{ affected, remaining }` — a store's bounded bulk verb. Decided and audited once (`admin.batch.matching`); a destructive one types `<entity>:all matching`. Checked rows still run row by row. Requires `batch` |
 | `batch.threshold` | past it, one `admin.batch` job per `chunk` (default: the threshold), run by a worker as the operator who queued it. The worker must load the module calling `defineAdmin` (`X_ADMIN_MOUNT_MISSING`) |
-| destructive | one row: type `<entity>:<id>`; a batch: type `<entity>:<n> rows` |
+| `readonly` | the action changes nothing (an export, a verification): its admin-level gate is `admin:read`, not `admin:write`, so a read-only staff role and an `admin:read` MCP token may run it. `destructive` (`admin:destroy`) and `matching` (`admin:write`) win over it |
+| destructive | gated on `admin:destroy`; one row: type `<entity>:<id>`; a batch: type `<entity>:<n> rows` |
 | MCP | still ONE tool, `admin.action.<name>`; a batch action's takes `ids: [...]` |
 | `labelKey` | the button's, the form's and the batch bar's label; absent: `admin.action.<name>` |
 
@@ -254,10 +267,11 @@ transaction as the write (`AuditLog.atomic`) — a CRUD write, an action's handl
 set and a queued batch's enqueues alike, so an entry that cannot be written rolls the work back
 and the log holds one `failed` entry — and reads it back by keyset. An allowed READ is not
 written unless `reads: true` — a refused one always is. Sealed and `sensitive` values reach the
-table only as `[redacted]`. `memoryAuditLog()` is a ring that forgets at every restart. The
+table only as `[redacted]` — `@ultimat3/core`'s `REDACTED`, the logger's marker too. `memoryAuditLog()` is a ring that forgets at every restart. The
 table is applied at boot with every other framework table (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`),
 from the leaf module `@ultimat3/admin/schema` (`SQL_ADMIN_AUDIT_TABLE`, `ADMIN_AUDIT_TABLE`) —
-no migration, no screen loaded to install it.
+no migration, no screen loaded to install it. That subpath is their one import path: 25.0.0 took
+them off the barrel.
 
 ### A sealed column
 
@@ -428,6 +442,23 @@ export const mcp = adminMcp({ app: admin, actor: (session) => actorFor(session.t
 adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publish
 ```
 
+Every tool carries a **scope**, the admin-level permission it needs. The MCP registry asks, in
+order: visibility — the actor's own admin authz (`adminMcpTools`); a tool it denies is ABSENT and
+answers tool-not-found, whatever the token holds — then the token's scope (`X_MCP_SCOPE_DENIED`
+naming it, before any argument is validated or a handler runs), then the call's own row-level
+decision inside the tool:
+
+| Scope | Tools |
+|---|---|
+| `admin:read` | `admin.<entity>.list`, `admin.<entity>.read`, `admin.search`, a `readonly` action |
+| `admin:write` | `admin.<entity>.create`, `admin.<entity>.update`, any other action |
+| `admin:destroy` | `admin.<entity>.delete`, a `destructive` action |
+
+The token's scopes are what `actor(session)` returns as `tokenScopes` (`AdminMcpActor`), expanded by
+`adminTokenScopes` (`admin:destroy` ⇒ `admin:write` ⇒ `admin:read`): `tokenScopes: ['admin:read']`
+is a read-only agent token. Absent, the token is as strong as its actor. A stdio host builds its
+caller's `scopes` with `adminTokenScopes(granted)` too — an empty set is refused every tool.
+
 The list tool takes the list screen's own grammar: `scope` by name and `where` as
 `[{ field, op?, value }]`, through the same validator a URL passes — and the resource's `rows`
 narrows what an agent reads whatever it sends.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "24.0.0",
+  "version": "25.1.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -27,27 +27,27 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "24.0.0",
-    "@ultimat3/ai": "24.0.0",
-    "@ultimat3/cache": "24.0.0",
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/db": "24.0.0",
-    "@ultimat3/entity": "24.0.0",
-    "@ultimat3/i18n": "24.0.0",
-    "@ultimat3/jobs": "24.0.0",
-    "@ultimat3/mcp": "24.0.0",
-    "@ultimat3/money": "24.0.0",
-    "@ultimat3/policy": "24.0.0",
-    "@ultimat3/query": "24.0.0",
-    "@ultimat3/render": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/ui": "24.0.0"
+    "@ultimat3/action": "25.1.0",
+    "@ultimat3/ai": "25.1.0",
+    "@ultimat3/cache": "25.1.0",
+    "@ultimat3/core": "25.1.0",
+    "@ultimat3/db": "25.1.0",
+    "@ultimat3/entity": "25.1.0",
+    "@ultimat3/i18n": "25.1.0",
+    "@ultimat3/jobs": "25.1.0",
+    "@ultimat3/mcp": "25.1.0",
+    "@ultimat3/money": "25.1.0",
+    "@ultimat3/policy": "25.1.0",
+    "@ultimat3/query": "25.1.0",
+    "@ultimat3/render": "25.1.0",
+    "@ultimat3/schema": "25.1.0",
+    "@ultimat3/ui": "25.1.0"
   }
 }

package/src/action-gate.ts

@@ -16,7 +16,9 @@ import { atomicallyAudited } from './crud-outcome';
 import { AdminActionNotApplicableError } from './errors';
 import {
   ADMIN_DESTROY,
+  ADMIN_READ,
   ADMIN_WRITE,
+  type AdminPermission,
   CONFIRMATION_REQUIRED_REASON,
   confirmationToken,
 } from './permissions';
@@ -47,11 +49,26 @@ export const ACTION_NOT_APPLICABLE_REASON = 'admin.error.action-not-applicable';
 /** The reason an action whose input its own schema refused is audited with. */
 const ACTION_INVALID_REASON = 'admin.error.invalid-input';
 
+/**
+ * The admin-level gate an action needs, and the MCP scope its tool carries. `destructive` is
+ * checked first so a declaration marked both `readonly` and `destructive` gets the stricter gate —
+ * a contradiction that fails closed rather than open.
+ */
+export function adminPermissionForAction<Input, Output>(
+  action: AdminAction<Input, Output>,
+): AdminPermission {
+  if (action.destructive === true) return ADMIN_DESTROY;
+  // `matching` CHANGES every row the list matches (its contract answers how many it changed), so a
+  // `readonly` beside it is the same contradiction as beside `destructive`: the write gate holds.
+  if (action.matching !== undefined) return ADMIN_WRITE;
+  return action.readonly === true ? ADMIN_READ : ADMIN_WRITE;
+}
+
 /** The permissions an action needs: the admin-level gate, then the action's own policy. */
 export function permissionsForAction<Input, Output>(
   action: AdminAction<Input, Output>,
 ): readonly string[] {
-  return [action.destructive === true ? ADMIN_DESTROY : ADMIN_WRITE, action.permission];
+  return [adminPermissionForAction(action), action.permission];
 }
 
 export function decideAction<Input, Output>(

package/src/admin.module.scss

@@ -12,27 +12,125 @@
   background: t.role('bg');
   color: t.role('fg');
 
-  // One column under the `md` rung: the sidebar becomes a block above the screen it navigates.
+  // One column under the `md` rung: the menu bar, then the screen; the sidebar is the panel the
+  // bar opens — or, in an engine with no popovers, a block above the screen it navigates.
   @include t.respond-down('md') {
     grid-template-columns: 1fr;
+    gap: 0;
   }
 }
 
+// Off-screen until focused, then pinned at the inline-start corner. It used to stay visually
+// hidden even WITH focus — the focus ring drew around a 1px box nobody could see.
 .skip {
-  @include t.visually-hidden;
+  @include t.focus-ring;
+
+  position: fixed;
+  z-index: t.z(skip-nav);
+  inset-block-start: t.space(2);
+  inset-inline-start: t.space(2);
+  padding-block: t.space(2);
+  padding-inline: t.space(4);
+  border-radius: t.radius('md');
+  background: t.role('surface-raised');
+  color: t.role('fg-strong');
+  box-shadow: t.shadow(md);
+  text-decoration: none;
 
-  &:focus-visible {
-    @include t.focus-ring;
+  &:not(:focus-visible) {
+    @include t.visually-hidden;
   }
 }
 
+// Hidden unless the engine can open the panel: a menu button that does nothing is worse than the
+// block an engine without popovers still shows.
+.bar {
+  display: none;
+}
+
+// A touch target: this bar exists for a phone.
+.menuButton,
+.close {
+  @include t.focus-ring;
+  @include t.touch-target;
+
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(2);
+  padding-inline: t.space(3);
+  border: 0;
+  border-radius: t.radius('md');
+  background: none;
+  color: t.role('fg-strong');
+  font: inherit;
+  cursor: pointer;
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+.close {
+  display: none;
+  justify-content: center;
+  align-self: flex-end;
+}
+
+// Every `[popover]` gets a UA style — fixed, centred, hidden while closed — so the column undoes
+// each; this box is the sidebar at `md` and up, and at every width where there is no popover.
 .side {
   @include t.surface('surface', 'sm');
   @include t.padding-block(t.space(6));
   @include t.padding-inline(t.space(4));
   @include t.column(t.space(4));
 
+  position: static;
+  inset: auto;
+  inline-size: auto;
+  block-size: auto;
+  margin: 0;
+  color: t.role('fg');
   border-inline-end: t.stroke(hairline) solid t.role('line');
+  overflow: auto;
+}
+
+@include t.respond-down('md') {
+  @supports selector(:popover-open) {
+    .bar {
+      display: flex;
+      align-items: center;
+      padding-block: t.space(1);
+      padding-inline: t.space(2);
+      border-block-end: t.stroke(hairline) solid t.role('line');
+      background: t.role('surface');
+    }
+
+    .side:not(:popover-open) {
+      display: none;
+    }
+
+    // The same edge sheet as `Drawer`'s inline-start side: raised surface, line edge, scrim.
+    .side:popover-open {
+      @include t.scrim-backdrop;
+
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      inset-inline-end: auto;
+      inline-size: min(t.rem(320), calc(100vw - #{t.space(12)}));
+      block-size: 100dvh;
+      max-block-size: 100dvh;
+      border: 0;
+      border-inline-end: t.stroke(hairline) solid t.role('line');
+      border-radius: 0;
+      background: t.role('surface-raised');
+      box-shadow: t.shadow(xl);
+    }
+
+    .close {
+      display: inline-flex;
+    }
+  }
 }
 
 .brand {
@@ -50,8 +148,17 @@
   color: t.role('fg-muted');
 }
 
+// One track that may shrink to the column: an `auto` track is at least its content's min-content
+// width, and a text input's is its `size` — wider than a 256px sidebar's content box, so the box
+// stuck out past the sidebar's edge at every width.
 .search {
   display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  min-inline-size: 0;
+
+  > form {
+    min-inline-size: 0;
+  }
 }
 
 .hidden {
@@ -96,6 +203,13 @@
   &:focus-visible {
     @include t.focus-ring;
   }
+
+  // A touch-target row on a narrow screen, where the link is tapped rather than clicked.
+  @include t.respond-down('md') {
+    display: flex;
+    align-items: center;
+    min-block-size: t.touch(target);
+  }
 }
 
 .main {

package/src/audit-pg.ts

@@ -2,7 +2,7 @@
 // `defineAdmin({ audit: postgresAuditLog() })` names — the memory log is a ring that forgets at
 // every restart, and a row's history that ends at the last deploy is not a history.
 
-import { isUltimateError, uuid } from '@ultimat3/core';
+import { isUltimateError, uuidV7 } from '@ultimat3/core';
 import { type DbClient, db, withTransaction } from '@ultimat3/db';
 import {
   AUDIT_READ_OPERATIONS,
@@ -149,7 +149,7 @@ export interface PostgresAuditLogOptions {
  */
 export function postgresAuditLog(options: PostgresAuditLogOptions = {}): AuditLog {
   const now = options.now ?? ((): Date => new Date());
-  const nextId = options.nextId ?? uuid;
+  const nextId = options.nextId ?? uuidV7;
   const sinks = options.sinks ?? [];
   const reads = options.reads === true;
   // Resolved per statement, never captured: inside `atomic` it is the open transaction.
@@ -160,7 +160,7 @@ export function postgresAuditLog(options: PostgresAuditLogOptions = {}): AuditLo
     async append(draft: AuditDraft): Promise<AuditEntry> {
       const entry = auditEntry(draft, nextId(), now());
       if (reads || !isAllowedRead(entry)) {
-        // A plain `{ text, values }`, the shape `pgExecutorFor` hands the same client: the text
+        // A plain `{ text, values }`, the shape `dbExecutor` hands the same client: the text
         // is this file's constant and every value is bound.
         await client().query({
           text: SQL_ADMIN_AUDIT_INSERT,

package/src/audit.ts

@@ -2,12 +2,10 @@
 // If it isn't logged, it didn't happen — so denied and failed attempts are logged too, and
 // there is deliberately no update or delete on this interface.
 
-import { canonicalJson, finiteCount } from '@ultimat3/core';
+import { canonicalJson, finiteCount, REDACTED } from '@ultimat3/core';
 import type { AdminActor, AdminDecision } from './authz';
 import type { AdminRow } from './registry';
 
-export const REDACTED = '[redacted]';
-
 /** Named once, so both refusals below say the same thing about the same call. */
 const SUBJECT = 'memoryAuditLog';
 

package/src/authz.ts

@@ -62,7 +62,7 @@ export interface AdminAuthz {
   decide(query: AdminAuthzQuery): AdminDecision;
 }
 
-export function allowed(
+export function adminAllowed(
   permission: string,
   reason: string,
   trace: readonly string[] = [],
@@ -70,7 +70,7 @@ export function allowed(
   return { allowed: true, permission, reason, trace };
 }
 
-export function denied(
+export function adminDenied(
   permission: string,
   reason: string,
   trace: readonly string[] = [],
@@ -82,7 +82,7 @@ export function denied(
  * Every permission must hold. The first denial wins, and carries its own reason.
  *
  * An EMPTY list is refused, never granted. `permissions[length - 1] ?? ''` used to fall through to
- * `allowed('')`, so a declared-but-empty gate opened for every actor, anonymous included — and the
+ * `adminAllowed('')`, so a declared-but-empty gate opened for every actor, anonymous included — and the
  * decision it returned named no permission at all. `visibleNav` hands an author's
  * `item.permissions` straight here, so `permissions: []` on a nav item was that gate. `pages.ts`
  * already refuses an empty page list at declaration time (`X_ADMIN_PAGE_UNGUARDED`); this is the
@@ -96,7 +96,7 @@ export function decideAll(
   subject?: AdminSubject,
 ): AdminDecision {
   if (permissions.length === 0) {
-    return denied('', 'admin.policy.none-declared', [
+    return adminDenied('', 'admin.policy.none-declared', [
       'no permission was declared for this surface, so there is nothing to satisfy',
     ]);
   }
@@ -107,10 +107,10 @@ export function decideAll(
     );
     trace.push(`${permission}: ${decision.allowed ? 'allow' : 'deny'} (${decision.reason})`);
     if (!decision.allowed)
-      return denied(permission, decision.reason, [...trace, ...decision.trace]);
+      return adminDenied(permission, decision.reason, [...trace, ...decision.trace]);
   }
   const last = permissions[permissions.length - 1] ?? '';
-  return allowed(last, 'admin.policy.all-granted', trace);
+  return adminAllowed(last, 'admin.policy.all-granted', trace);
 }
 
 export function isAllowed(
@@ -167,8 +167,8 @@ export function staticAuthz(granted: readonly string[]): AdminAuthz {
   return {
     decide({ permission }): AdminDecision {
       return set.has(permission)
-        ? allowed(permission, 'admin.policy.granted', [`static: ${permission} in grant list`])
-        : denied(permission, 'admin.policy.not-granted', [
+        ? adminAllowed(permission, 'admin.policy.granted', [`static: ${permission} in grant list`])
+        : adminDenied(permission, 'admin.policy.not-granted', [
             `static: ${permission} not in [${[...set].join(', ')}]`,
           ]);
     },

package/src/batch.ts

@@ -4,19 +4,14 @@
 
 import { finiteCount } from '@ultimat3/core';
 import { expectedQueryLoop } from '@ultimat3/db';
-import { decideAction } from './action-gate';
+import { adminPermissionForAction, decideAction } from './action-gate';
 import { invokeRowAction } from './action-row';
 import type { AdminDecision } from './authz';
 import { runMatching } from './batch-matching';
 import { queueBatch } from './batch-queue';
 import { type CrudCtx, decideOperation } from './crud';
 import { type AdminListRequest, listWhere } from './list-scope';
-import {
-  ADMIN_DESTROY,
-  ADMIN_WRITE,
-  CONFIRMATION_REQUIRED_REASON,
-  confirmationToken,
-} from './permissions';
+import { ADMIN_DESTROY, CONFIRMATION_REQUIRED_REASON, confirmationToken } from './permissions';
 import type { AdminAction, AdminFilter } from './registry';
 import { rowId } from './registry';
 import { type AdminResource, repoOf } from './resource';
@@ -202,7 +197,7 @@ export async function runAdminBatch(input: AdminBatchInput): Promise<AdminBatchA
   if (action.batch === undefined) {
     return denied({
       allowed: false,
-      permission: action.destructive === true ? ADMIN_DESTROY : ADMIN_WRITE,
+      permission: adminPermissionForAction(action),
       reason: BATCH_NOT_OFFERED_REASON,
       trace: [`batch: ${action.name} does not declare batch`],
     });

package/src/crud-input.ts

@@ -2,7 +2,8 @@
 // tenant column taken out of the caller's hands, and the audit diff of what the write changed.
 // Pure over the resource — `crud.ts` decides and writes, this file only shapes the input.
 
-import { type AuditFieldDiff, diffRows, REDACTED } from './audit';
+import { REDACTED } from '@ultimat3/core';
+import { type AuditFieldDiff, diffRows } from './audit';
 import type { CrudCtx } from './crud';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';

package/src/describe.ts

@@ -36,6 +36,10 @@ export interface AdminActionDescription {
   readonly batch: boolean;
   /** Rows a batch runs inline before it is queued as `admin.batch` jobs. `null`: always inline. */
   readonly threshold: number | null;
+  /** Declared `readonly`: its admin gate is `admin:read` — unless `destructive` or `matching` holds it. */
+  readonly readonly: boolean;
+  /** It declares `matching`: "all matching" is ONE set-based write, which keeps the write gate. */
+  readonly matching: boolean;
 }
 
 export interface AdminResourceDescription {
@@ -88,6 +92,8 @@ const actionOf = (action: AdminAction): AdminActionDescription => ({
   when: action.when !== undefined,
   batch: action.batch !== undefined,
   threshold: batchPlan(action)?.threshold ?? null,
+  readonly: action.readonly === true,
+  matching: action.matching !== undefined,
 });
 
 /** Sorted by name and by URL, so two boots of one app describe it in the same bytes. */

package/src/dev/data.ts

@@ -144,8 +144,8 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
 
   const sources: DevSources = {
     async routes(): Promise<readonly RouteFact[]> {
-      const { describeRoutes } = await import('@ultimat3/render');
-      return describeRoutes().map((route) => ({
+      const { describePages } = await import('@ultimat3/render');
+      return describePages().map((route) => ({
         path: route.path,
         // `RouteDescriptor` calls the render mode `mode`; the panel's own word is `render`, and
         // the two are bridged here, once. Reading `route['render']` answered `undefined` for