@ultimat3/admin
v31.49.0
Published
Two dashboards: the /_x framework dev panels and the generated, AI-first app admin
Maintainers
Readme
@ultimat3/admin 🛠️
Two dashboards live here. They are not the same thing — and they have two doors.
bun add @ultimat3/admin · guide: Admin Dashboard
import { staticAuthz } from '@ultimat3/admin';
import { defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
const authz = staticAuthz(['admin:read']);
const actors = [{ id: 'dev-admin', roles: ['admin'] }];
export const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // /_x| | /_x — framework dev dashboard | admin — generated app admin |
|---|---|---|
| Import | @ultimat3/admin/dev | @ultimat3/admin |
| 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 (describePages, inspect, dependentsOf, …) | the entity registry + repos |
| Shipped in the app image | never mounted | mounted at /admin |
/_x panels
One panel per file. Each kills one question, and each is available as --json — the tab is a rendering of the payload, not a second source.
| Panel | Kills |
|---|---|
| routes | which handler serves this? — render mode, offline strategy, revalidate tags, budget |
| 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 | 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, DEV_SQL_MAX_ROWS and the SELECT-only role ensureReadOnlyRole grants), schema + drift (null unless a host wires the check) |
| mail | caught mail, rendered, per locale, with the locale gaps listed; beside it every declared mail's preview rendered per locale (mailTemplates, the host's source: x dev wires it) |
| cache | the tag graph — what invalidated what, and which tags are orphans |
| policy | the permission matrix per actor, every cell carrying its trace |
| manifest | emitted x.manifest.json diffed against the committed one |
import { staticAuthz } from '@ultimat3/admin';
import { defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
declare const request: Request;
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 fromThe root barrel does not re-export any of this: x dev mounts /_x without pulling a Solid
component tree into the process, and an admin view cannot reach a dev panel by accident.
The generated admin
One call, a working CRUD admin at a URL: columns from the entity's columns, filters from indexed columns, validation from the entity's schema, labels from i18n keys, rows through the app's own typed handle. The app writes no page, no screen glue and no repo adapter.
import { type AdminDb, type AdminEntity, defineAdmin } from '@ultimat3/admin';
// Your app's `entity()` results and its `database()` handle — `@app/db` in a scaffolded app.
declare const posts: AdminEntity;
declare const users: AdminEntity;
declare const db: AdminDb;
export const admin = defineAdmin({ entities: [posts, users], db });x dev and the container mount it: /admin, /admin/posts, /admin/posts/new,
/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".
count: 'estimate' instead reads AdminRepo.approximateCount() — the planner's whole-table
figure, constant time — when the resource declares no rows scope and the estimate is at least
10,000 rows; the tile reads ~1,200,000 (admin.dashboard.records.approximate). Anything else —
a row scope, a small or never-analysed table, a tenant-scoped or soft-deleting one the estimate
refuses — is the exact count().
| 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, 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 — an AdminActor: id, kind, roles, permissions, scopes, orgId, onBehalfOf, locale, timeZone. Every decision is evaluated against core's Actor OF THAT KIND (absent kind = 'user'), so a rule reading actor.kind, scopes or onBehalfOf fires on the admin, its MCP surface and a queued batch chunk alike | the actor the HTTP pipeline resolved for the request |
| auth.authz | the one decision path | roleAuthz() — the role map decides each permission by name |
| audit | postgresAuditLog() (the table x_admin_audit) or memoryAuditLog({ sinks }) | a memory ring |
Three authz constructors, one interface: roleAuthz() (the default), policyAuthz({ policies })
when a rule reads the row or the tenant (a permission the map omits falls back to the role map), singlePolicyAuthz(policy) when one grant runs the whole
admin.
No script
Every route is ssr, hydrate: 'never' (unless an app file claimed it — Custom pages, below), and every control is a link or a native form: the pager
is <Pagination hrefFor>, a sort header is a link, scope tabs are links, the filter bar is one
GET form, a form posts at the URL that rendered it and a refused one comes back 422 with what was
typed. A write that worked is a 303. Every admin document is noindex, nofollow, and carries no
og:* or twitter:* tag (@ultimat3/seo withdraws them from a noindex document unless the
route declares socialCard: true; no admin route declares it).
The list an operator works in
The list's whole state is its URL — one parser and one builder (pageRequestOf, listHref):
| Parameter | Means | Refused when |
|---|---|---|
| ?cursor=<signed> | keyset position on (sort, id) — any number of tied values, and NULLs (last ascending, first descending), are reached | never — an unreadable cursor is page one |
| ?sort=<field>:<asc\|desc> | order; a bare field is desc | the field is not sortable, or the direction is neither |
| ?scope=<name> | a declared scope; absent is the default one; * is NO scope, not even the default (a related card's "all" link) | no scope has that name; * cannot be declared |
| ?f.<field>=<value> | a filter, by the field's default operator | the field is not a filter of the resource |
| ?f.<field>.<op>=<value> | a named operator; repeat the parameter for in | the field's shape does not answer <op>, or the value is not the column's type — a number is decimal digits (no blank, hex or exponent), a date is one the calendar has |
| anything else | — | always |
A refusal is X_ADMIN_FILTER_INVALID, a 400 naming what the list does answer — never the
unfiltered list. An empty value is no parameter: a GET form submits every input it holds.
| Filter shape | Derived for | Control | Operators (first is the default) |
|---|---|---|---|
| text | a text column contains runs against — the label always, others when indexed; case-insensitive (ilike, served by a gin_trgm_ops index) | search box | contains eq neq is-null |
| exact | a uuid, bigint or numeric column | text box | eq neq in is-null |
| choice | an enum (its own values, labelled by the catalog), a locale, a zone | select | eq neq in is-null |
| boolean | a boolean | any / yes / no | eq |
| range | a number, a date, a timestamp (typed in UTC) | from / to | eq neq gt gte lt lte is-null |
| reference | a foreign key | the target's rows by label, or its lookup | eq neq in is-null |
Money, JSON, file, sealed and tenant columns derive no filter.
import { defineAdmin } from '@ultimat3/admin';
import { database, entity, text, timestamp, uuid } from '@ultimat3/entity';
const owners = entity('owners', { columns: { id: uuid().primaryKey(), name: text() } });
const tickets = entity('tickets', {
columns: {
id: uuid().primaryKey(),
title: text(),
status: text(),
assigneeId: uuid(),
region: text(),
createdAt: timestamp().defaultNow(),
},
});
const db = database({ owners, tickets });
defineAdmin({
entities: [tickets, owners],
db,
resources: {
tickets: {
labelField: 'title',
// Tabs. At most one default; a count is one query per tab that asks for it.
scopes: {
open: { where: [{ field: 'status', op: 'eq', value: 'open' }], default: true, count: true },
mine: { where: (actor) => [{ field: 'assigneeId', op: 'eq', value: actor.id }] },
},
// Who sees which rows at all — list, search, detail, lookup, labels and MCP alike.
rows: (actor) => [{ field: 'region', op: 'eq', value: actor.locale ?? '' }],
// Computed list columns: one of six renderers, or a component.
columns: {
age: { value: (row) => row['createdAt'], render: 'relative-time' },
state: { value: (row) => ({ label: row['status'], tone: 'warning' }), render: 'badge' },
},
},
},
});| Declared | Rule |
|---|---|
| scopes.<name> | where is predicates or (actor) => predicates; default: true at most once; count: true reads AdminRepo.count — never the caller's filters, so a tab's number is the scope's size |
| rows | applied by every read of the resource; a row outside it is "not found", exactly as a missing one |
| a declared contains | in rows or a scope's where: case-SENSITIVE (like, caseSensitive: true on the filter), on the read and the write — a row scope is authorization and never widens. Only what an operator types — search, list filter, lookup — ignores case |
| columns.<name> | render: badge · relative-time · money · truncate · link · json, or (props) => JSX; the row it reads carries no sealed column; a name that is also an entity column is refused |
| labelField | what a reference to this resource SHOWS, linked to the row; read once per page per target, never per row |
A reference filter or input is a <select> of the target's rows when it has at most 50
(LOOKUP_SELECT_MAX), else an id box beside the target's lookup screen
(/admin/<resource>/lookup) — one derived lookup per resource, contains on its label, behind
its own list gate and row scope, keyset-paged. No picker endpoint is written in the app.
Statements a list page issues: 1 for the rows, 1 per scope with count: true, 1 per referenced
resource (2 for one that is picked from and has more than 50 rows). 50 rows, two reference columns
and three scopes of which one is counted: 4, or 6 when both targets are large.
The detail page and the form
import type { AdminResourceOptions } from '@ultimat3/admin';
export const resources: Readonly<Record<string, AdminResourceOptions>> = {
users: {
// Titled groups; every field named in none falls into a default section drawn last.
sections: [{ titleKey: 'admin.users.section.profile', fields: ['handle', 'displayName'] }],
formGroups: [{ titleKey: 'admin.users.section.profile', fields: ['handle', 'displayName'] }],
// hasMany relations, by the name @ultimat3/entity gives them — each drawn as THAT
// resource's own list (its columns, its rows scope, its policy) filtered to this row.
related: ['posts', 'media'],
fields: {
handle: { hintKey: 'admin.users.hint.handle', on: 'create' }, // set once, never edited
},
},
};| Declared | Rule |
|---|---|
| sections / formGroups | a name that is not a drawn field, or that two groups claim, is X_ADMIN_FIELD_UNSUPPORTED at defineAdmin |
| related | a hasMany of the entity whose rows are a resource of this admin; anything else refused at defineAdmin. A target the actor may not list is left off the page |
| on | the field is an input on one side only, and a write from the other side drops it |
| hintKey | the line under the control, through t() |
The detail page's history card is audit.entries({ entity, entityId, changes: true }) — and
orgId when the actor has one, as on /admin/audit — newest first, 20 per page, older pages by
keyset (?history=). Statements a detail page issues: 1 for
the row (2 with rows), 1 per related list, 1 per referenced target for the whole page, 1 for
the history with postgresAuditLog.
Actions: a form, a row state, a batch
import type { AdminAction } from '@ultimat3/admin';
import { t } from '@ultimat3/schema';
declare function suspend(id: unknown, reason: unknown): Promise<void>;
export const suspendUser: AdminAction = {
name: 'user.suspend',
permission: 'users:suspend',
entity: 'users',
input: t.object({ reason: t.string.min(3) }), // the action's own form; absent: a confirm only
when: (row) => row['suspended'] !== true, // the button, each list row, AND the server
batch: { threshold: 200 }, // or `true`: always inline
handle: async ({ input }) => suspend(input['id'], input['reason']),
};| Piece | Behaviour |
|---|---|
| input | the button links to <row>?action=<name>; the form posts input.<field>, labelled admin.input.<name>.<field>; a refusal is a 422 with each issue on its field |
| when(row) | hides the button where it answers false and is asked again before the handler: X_ADMIN_ACTION_NOT_APPLICABLE, a 409. The row carries no sealed column |
| 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; checked rows past the bound answer after: null — re-check the rest, never widened to all |
| 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) |
| 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> |
Every key a declaration derives — branding, nav, titles, fields, sections, scopes, columns, action
labels and their input fields — is admin.catalogKeys(), sorted. x verify's i18n step asks
each of the app's catalogs for exactly that list (X_CATALOG_MISSING_KEYS).
No script, anywhere: row checkboxes join the bar's form by their form attribute, and a
confirmation is a server round trip. An action on a row the actor cannot see — gone, or outside
its rows — is refused whether or not it declares when.
The jobs dashboard
Every defineAdmin() carries it; the app declares nothing. Four resources over the queue's
operator surface (JobIntrospection), each an ordinary resource with a repo:, and one screen:
| Path | What | Actions (job:manage) |
|---|---|---|
| /admin/jobs | depth tiles from one stats(), workers, oldest ready; done-vs-failed over ?range=1h\|24h\|7d\|30d; volume, failure rate and mean duration per job name. A declared 30 s <meta http-equiv="refresh"> | — |
| /admin/jobs/runs (x_jobs) | one tab per state; filters by id prefix (the search box), name, queue, state, tenant, created time; a row's input (redacted by @ultimat3/jobs), steps, error and stack, progress, trace | retry (dead), retry from a step, run now (waiting on its clock), cancel (live), remove — the batched ones over checked rows or "all matching" through requeueMany / promoteMany / removeMany |
| /admin/jobs/queues (x_job_queues) | depth per state, paused | pause, resume |
| /admin/jobs/tasks (x_job_tasks) | schedule, zone, last fire (taskFires()), next fire (nextTaskRun), paused | pause, resume, run now |
| /admin/jobs/workers (x_job_workers) | identity, host, queues, in flight, heartbeat | — |
| Permission | Grants |
|---|---|
| job:read (JOB_READ) | every jobs screen and MCP read; no control renders |
| job:manage (JOB_MANAGE) | every action, behind admin:write (or admin:destroy for remove) — refused on the server when forged |
An actor with an orgId sees that org's job rows only (jobRowScope) and none of the fleet —
queues, tasks, workers and the overview's figures are every tenant's. Override either with
resources: { x_jobs: { rows } }. MCP: admin.x_jobs.list, admin.x_jobs.read,
admin.x_job_tasks.list, admin.action.job.retry, admin.action.job.queue.pause, … — the
admin's own projection. /_x/jobs draws the same overview component over the dev queue.
The audit log
postgresAuditLog() writes one row per audited write to x_admin_audit, in the same
transaction as the write (AuditLog.atomic) — a CRUD write, an action's handler, a matching
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] — @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. That subpath is their one import path: 25.0.0 took
them off the barrel. x_error_groups (SQL_ERROR_GROUPS_TABLE, ERROR_GROUPS_TABLE) rides the
same subpath.
Error groups (As of 2026-11). @ultimat3/admin/error-groups is the sink and its stores, and
nothing else, because every role installs it: errorGroupsSink({ store, onNewGroup?, ignore?,
perMinute? }) is an ErrorReporter folding each report into its errorFingerprint group —
outside the request's transaction, capped per minute, onNewGroup (a job handle) enqueued once
per new group fleet-wide (xmax = 0). Install it beside any other reporter with core's
chainErrorReporters. Stores: postgresErrorGroupsStore(), memoryErrorGroupsStore();
retention errorGroupsPurgeTarget(store, { olderThanMs }). The screens are the barrel's:
pages: errorGroupsPages({ store, navGroup? }) mounts /admin/errors behind errors:read
(ERRORS_READ).
/admin/audit is the whole trail, 100 entries per page, newest first, behind one native GET form:
?entity=, ?actor=, ?outcome=, ?since=, ?until= (an instant with an offset or Z, a
bare YYYY-MM-DD as that day's first UTC instant, or the form's YYYY-MM-DDTHH:mm, given its
Z by utcFormInstantOf and nowhere else; until is exclusive), ?changes=1, and the
keyset ?before=, which the older link writes with the filters kept. auditRequestOf(url)
is the one parser and auditHref(path, request) the one builder; a parameter it does not
read (?org= too: the tenant is the actor's) is X_ADMIN_FILTER_INVALID, a 400. Both stores
take outcome, since and until (AuditQuery). An app's own log should too: the screen
re-checks every entry it returns with auditEntryMatches, so a log that ignores a field draws
a short page, never another tenant's or another outcome's entry. A diff on either screen
masks a sensitive or sealed field's value, whatever the stored entry holds.
A sealed column
.sealed() on the entity is read by nothing here: no list column, no detail row, no filter, no
search field, no MCP argument. It is in resource.secretFields — a list of its own — and the form
renders it as a password input with no value. Empty on an edit means unchanged; a required one is
required to create. The audit diff records that it changed, as [redacted].
The views are TSX, and the pieces come apart
Every renderer is an ordinary component in an ordinary .tsx file importing @ultimat3/ui —
AdminList, AdminForm, AdminDetail, AdminActions, Widget, AdminLayout are each exported,
so a table can be lifted into a screen the generator never wrote:
import {
type AdminApp,
type AdminField,
AdminList,
type AdminListProps,
type AdminRow,
listHref,
Widget,
} from '@ultimat3/admin';
declare const admin: AdminApp;
declare const list: AdminListProps<AdminRow>;
declare const field: AdminField;
declare const row: { readonly total: number };
const { resource, page, ctx, actor, authz, request, scope, counts } = list;
<AdminList resource={resource} page={page} error={null} ctx={ctx} actor={actor} authz={authz}
basePath={admin.basePath} request={request} scope={scope} counts={counts}
hrefFor={(location) => listHref(admin.basePath, resource, location)} />;
<Widget field={field} value={row.total} ctx={ctx} mode="read" />;Widget takes the field and the raw row value, not pre-derived props: the internal
widgetProps() is the guard (money is minor units, a timestamp has an IANA zone) and the component
calls it, so there is no way to render a cell that skipped it.
Mounting it yourself
x dev and the container already do. A host that is neither asks the route table per request:
import { type AdminApp, adminRouteMatch } from '@ultimat3/admin';
declare const admin: AdminApp;
declare const url: URL;
declare const request: Request;
const matched = adminRouteMatch(admin, url.pathname); // null → 404
if (matched === null) throw new Response(null, { status: 404 });
const answer = await matched.route.respond({
ctx: await admin.requestCtx(request), params: matched.params, url: url.href,
method: 'GET', form: null, // or 'POST' + the parsed form
});
// { kind: 'document', status, body } — the framed screen — or { kind: 'redirect', location }respond is the only way in: the screen decides before it renders, so a host serialises and
nothing else.
Custom pages
The bespoke ops screen is the common case, not the corner: a reconciliation fixer, a proxy health
board, a deploy button. Declare it in pages: and it becomes a real admin route.
// admin/ops/page.tsx — a component, nothing framework-shaped about it
import { type AdminAuth, type AdminPageProps, type CrudCtx, defineAdmin } from '@ultimat3/admin';
import { database, entity, uuid } from '@ultimat3/entity';
import { type JSX } from 'solid-js';
type Counts = Readonly<Record<string, number>>;
declare function mediaStateCounts(ctx: CrudCtx): Promise<Counts>;
declare function OpsBoard(props: { readonly counts: Counts }): JSX.Element;
declare const auth: Partial<AdminAuth>;
const posts = entity('posts', { columns: { id: uuid().primaryKey() } });
const db = database({ posts });
export async function OpsPage(props: AdminPageProps): Promise<JSX.Element> {
return <OpsBoard counts={await mediaStateCounts(props.ctx)} />;
}
// admin/index.ts
defineAdmin({
entities: [posts],
db,
pages: [
{
path: '/ops', // rooted at basePath → /admin/ops
titleKey: 'admin.ops.title',
navGroup: 'admin.group.operations', // omit to keep it out of the nav
permissions: ['ops:read'], // `admin:read` is composed in front of it
component: OpsPage,
},
],
auth,
});| What you get | How |
|---|---|
| a row in app.routes, adminRoutes(), x routes, x manifest | pageRoutes() folds it in beside the generated screens; every admin route is in the framework's route list as a MOUNTED route with its permissions |
| a nav item that disappears for an actor who cannot open it | NavItem.permissions → visibleNav |
| a defineRoute({ policy }) you never wrote and cannot omit | adminRouteConfig composes permissions[0] into it |
| a per-request refusal, audited, answered 403, before your component runs | guardedScreen() wraps it in decideAll |
| the shell — nav, who is acting, search | the same frame every generated screen gets |
Testing one. A page component needs a CrudCtx, and adminTestCtx() mints it from a grant
list — no admin instance, no session:
import { type AdminPageProps, adminTestCtx } from '@ultimat3/admin';
import { renderView } from '@ultimat3/testing';
import { type JSX } from 'solid-js';
declare function OpsPage(props: AdminPageProps): Promise<JSX.Element>;
const view = await renderView(OpsPage, {
ctx: adminTestCtx({ granted: ['admin:read', 'ops:read'] }),
params: {},
url: 'http://localhost/admin/ops',
});x g admin:page <name> emits exactly this test beside the page.
The guard is not yours to remember. adminRoutes() hands a host the screen, never the
component you wrote, and AdminPageProps.ctx is required by the type — a page component cannot be
called without the handle the guard decides on. permissions: [] throws
X_ADMIN_PAGE_UNGUARDED where it is written, not on the first unauthenticated request. A path
that shadows a generated screen throws X_ADMIN_PAGE_PATH_INVALID the same way.
Custom pages are render: 'ssr', hydrate: 'never': the guard runs on the server, so there is
nothing to ship and nothing to decide twice. A refused one answers 403.
In your own shell, with an island: claim the route. A page.tsx at the page's path whose
config is claimAdminRoute(admin, path, { load?, hydrate?, budget?, navigation? }) serves it in
the catch-all's place — a file route, so its islands hydrate. The claim keeps the gate, meta and
a load that answers through the same screen (frame: 'none', no AdminLayout); the page
component renders data.body (decided: the page or the refusal) inside the app's shell, beside
data.nav and data.app (what load returned). Only a pages: entry or the dashboard; only the
config issued for that path (else X_ROUTE_DUPLICATE). Admin Dashboard → An admin page in your
own shell.
Splitting the admin across files
defineAdmin takes plain values — entities, db, resources, actions, jobs, pages,
nav, branding, auth, audit. Every one of them can be imported from its own module, so the cut is
along the input's own keys and there is exactly one layout:
app/admin/
index.ts defineAdmin({ … }) — composition only, no logic
auth.ts actor() + policyAuthz({ policies })
nav.ts groups, order, extras
<resource>/
resource.ts the AdminResourceOptions entry (listFields, sensitive, labelField)
actions.ts the AdminAction[] for this entity
pages/<name>.tsx a custom page component for this entity, if any
pages/<name>.tsx an app-wide custom page (ops, reconciliation, deploy)index.ts imports each and composes. Nothing here is a framework rule — it is what the input
shape already is, written down once so two apps do not invent two layouts. x g admin emits it.
Derived from the entity, and only from it
| Admin decision | Read from |
|---|---|
| field type + widget | $meta.kind, refined by values (select) and references (reference) |
| one line vs prose | text({ max }) has a length; text() does not |
| read-only | a generated default (uuid(), defaultNow(), onUpdateNow()) or a key column |
| filters, sort | $meta.index / unique / primaryKey — never an unindexed column, except the label (the list's search box); a money() column sorts by currency, then minor (amounts compare only within a currency) |
| row address | $primaryKey[0], composite keys included |
| validation | $schema, the entity's own Standard Schema |
| write-only | .sealed() — in secretFields, and in no list a reader iterates |
sensitive, a fixed currency and labelField have no entity source and are never guessed: declare them in resources: { <entity>: { … } } or they are absent.
Rules it enforces for you
| Rule | Where |
|---|---|
| Money is { minor, currency } — a float throws X_ADMIN_FIELD_UNSUPPORTED | widgetProps |
| A timestamp never renders without an IANA zone | assertZone |
| Pagination is keyset — AdminListQuery has no offset field | pagination.ts |
| A cursor is signed by @ultimat3/core and scoped to its resource — a forged or borrowed one is page one, never another table's position | pagination.ts |
| A button an actor cannot press is never rendered, and the call is refused by the same decision | action-gate.ts |
| Destructive operations re-confirm (<entity>:<id>) and are always audited | permissions.ts, crud.ts |
| Every mutation and every denial is on the audit log, with a before/after diff | audit.ts |
| An edit carries the row's version (_version); a row changed since the form was drawn is a 409, never overwritten. An instant posted back as drawn is left out of the patch | row-version.ts, form-decode.ts |
| Branding aliases tokens only — accent: '#7c3aed' is a compile error | theme.ts |
Reads are audited too, and on both branches: adminDetail keys its entry on the row,
adminList and adminSearch key theirs on the table (entityId: null), and a refusal is an
entry of its own. AdminSearchResult.audit carries one entry per resource the call decided
about — searched or refused — so a jump box that walked every readable entity leaves a trace.
Search asks an entity that declares .searchable() columns through its vector first —
search_tsv, the GIN index, one statement, matchedField: 'search_tsv' — then fills a short page
with the entity's contains per text field — case-insensitive, the ilike a gin_trgm_ops index
serves — so a whole word and a prefix ("ali" → "Alice") both find the row. At most 1 + 3
statements per resource, resources read four at a time, the row scope on every one. Hits are in
the resource's defaultSort, not ranked. A custom repo: opts in with search(query)
(AdminRepo.search, optional); the memory driver refuses a vector match (X_SEARCH_IN_MEMORY),
so there contains alone answers. As of 2026-11 the GIN index serves the vector read only when the
defaultSort is a column no btree covers: every handle read ends in the primary key, so a sort by
id (or an indexed column) with a limit walks that btree and filters @@ row by row — 139 ms
tenanted, 283 ms untenanted, against the GIN's 11 ms, on 200,000 rows. The fix is a relevance
order (ts_rank), which no btree serves: deferred with ranking (plan 101-finished slice 06 U2).
AI-first
The admin exposes its own MCP surface, derived from the same resources and gated by the same authz — an agent sees exactly the tools its actor could have clicked.
import {
type AdminApp,
type AdminMcpActor,
adminMcp,
adminMcpTools,
type CrudCtx,
} from '@ultimat3/admin';
declare const admin: AdminApp;
declare const ctx: CrudCtx;
declare function actorFor(token: string | undefined, facts: unknown): AdminMcpActor | null;
// apps/admin/mcp.ts — module scope: the mount serves every apps/<app>/mcp.ts, after the scan
export const mcp = adminMcp({
app: admin,
path: '/admin/mcp', // beside the web endpoint's /mcp
include: 'exposed', // the app's exposed actions (admin:write) and queries (admin:read) too
actor: ({ token, facts }) => actorFor(token, facts),
});
adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publishEvery 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 caller is an agent: resolveToken builds agentActor(...) from what actor(session)
returned, whatever kind it set, carrying its scopes (core's framework capabilities, never
tokenScopes), orgId and onBehalfOf — so can(perm, ({ actor }) => actor.kind !== 'agent')
refuses the tool here exactly as on the app's own routes.
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.
Opt-in AI panes, each declaring the scope it needs (aiPanes({ enable: ['anomaly'] })):
| Pane | Scope |
|---|---|
| anomaly | jobs:read, metrics:read |
| nl-query | db:read-only |
| backlog-forecast | jobs:read, metrics:read |
Panes are off until enabled, and runAiPane refuses (never no-ops) without a runner.
GatewayAdapter — the type a host narrows @ultimat3/ai's Gateway to an AiRunner with — is
@ultimat3/admin/adapter's, off the barrel.
Errors
X_ADMIN_ENTITY_UNKNOWN · X_ADMIN_FIELD_UNSUPPORTED · X_ADMIN_FILTER_INVALID · X_ADMIN_ACTION_NOT_APPLICABLE · X_ADMIN_MOUNT_MISSING · X_ADMIN_POLICY_MISSING · X_ADMIN_REPO_UNBOUND · X_ADMIN_PAGE_UNGUARDED · X_ADMIN_PAGE_PATH_INVALID · X_ADMIN_DENIED · X_ADMIN_TOOL_FORBIDDEN · X_ADMIN_INVALID · X_DEV_DASHBOARD_IN_PROD · X_NOT_IMPLEMENTED (an unwired /_x source, carrying the wiring line).
Error classes
Every error class src/index.ts exports, for instanceof inside one process. Across a wire or
a job boundary the class is gone and the code is what survives — match on that.
| Class | Code | Declared in |
|---|---|---|
| AdminActionDuplicateError | X_ADMIN_ACTION_DUPLICATE | src/errors.ts |
| AdminActionNotApplicableError | X_ADMIN_ACTION_NOT_APPLICABLE | src/errors.ts |
| AdminEntityUnknownError | X_ADMIN_ENTITY_UNKNOWN | src/errors.ts |
| AdminFieldUnsupportedError | X_ADMIN_FIELD_UNSUPPORTED | src/errors.ts |
| AdminFilterInvalidError | X_ADMIN_FILTER_INVALID | src/errors.ts |
| AdminMountMissingError | X_ADMIN_MOUNT_MISSING | src/errors.ts |
| AdminPagePathInvalidError | X_ADMIN_PAGE_PATH_INVALID | src/errors.ts |
| AdminPageUnguardedError | X_ADMIN_PAGE_UNGUARDED | src/errors.ts |
| AdminPolicyMissingError | X_ADMIN_POLICY_MISSING | src/errors.ts |
| AdminRepoUnboundError | X_ADMIN_REPO_UNBOUND | src/errors.ts |
| DevDashboardInProdError | X_DEV_DASHBOARD_IN_PROD | src/errors.ts |
| DevSourceUnavailableError (extends core's NotImplementedError) | X_NOT_IMPLEMENTED | src/errors.ts |
