@ultimat3/admin 27.0.0 → 27.2.0

package/CLAUDE.md

@@ -11,7 +11,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **The MCP caller is the ambient actor for the whole call, tenant included.** `mcp.ts` wraps `callAdminTool` in a child context (a fresh root one over stdio); `resolveToken` and `adminActorOf` both carry `orgId`. Pinned in `mcp-context.test.ts`, `mcp-tenant.test.ts`.
 - **`defineAdmin({ entities, db })` is a served admin; a host writes nothing.** `routes.ts` gives EVERY route a screen (`screens.ts` — a `Record<AdminView, …>`, so a new view cannot mount with nothing behind it) and `AdminRouteConfig.respond(request)` is the only way in: GET or a posted form in, `{ status, body }` or a 303 out. `repo-entity.ts` is the ONE adapter from the typed handle to `AdminRepo`; it adds no predicate (tenancy, soft delete, sealing and invariants are the handle's) and never spreads a row. A resource with neither a table in `db` nor a `repo:` is `X_ADMIN_REPO_UNBOUND` at `defineAdmin`. Pinned in `mounted-screens.test.ts`, `repo-entity.test.ts`, `admin-bind.test.ts`.
 - **A screen's guard is composed, never written.** A resource screen asks `crud.ts` FIRST and renders what it answered — only it holds the row a row-level rule reads. Every other screen (a `pages:` entry, dashboard, jobs, audit, search) is built through `guardedScreen()` (`screen-frame.tsx`): `decideAll` over the route's permissions, the refusal audited (`auditRefusal`), answered 403. `pages.ts` composes `[admin:read, …declared]`; `AdminPageProps.ctx` is required by the type; an empty permission list is `X_ADMIN_PAGE_UNGUARDED` at `defineAdmin`.
-- **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 `''`.
+- **No screen ships a script; an app file that CLAIMED its route may** (`claimAdminRoute`: a `pages:` entry or the dashboard; `load` = `screenFor`, `frame: 'none'`). Only a config `claims.ts` issued for that path passes `claimable`, else `X_ROUTE_DUPLICATE`. Every admin 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` (`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).
@@ -29,13 +29,12 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **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` → `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 bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes` (+ `claim-route.ts`, the `@ultimat3/http` bridge); `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** — `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.
 - **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider — in `panel-live`, `panel-db`, `panel-timeline` and `panel-cache` alike (`dev/panel-degrade.test.ts`). Everything else reaches `panelPayload`, which renders its code and its fix.
 - **What an entity does not declare, the admin does not invent.** `sensitive`, a fixed `currency` and `labelField` come from `AdminResourceOptions` or they are absent. Same rule for a URL: the reference widget links through `WidgetContext.hrefFor` or renders plain text — the route table is `AdminApp`'s.
 - **`panel-db.ts` executes the string `assertReadOnlyQuery` RETURNS**, never the textarea's bytes (`ReadOnlyVerdict`).
@@ -82,6 +81,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `admin.ts` / `mounts.ts` / `actor.ts` | `defineAdmin` → resources, repos, nav, route table, audit, authz / the registry a host mounts from / the default actor |
 | `pages.ts` / `page-guard.tsx` | a `pages:` entry → route + nav item (pure) / the refusal a screen renders and audits |
 | `route-config.ts` / `routes.ts` / `screens.ts` | the render bridge: `defineRoute`, `registerMountedRoutes` / route → screen, `adminRouteMatch` / view → screen |
+| `claim-route.ts` / `claims.ts` | an app file serving a route in the catch-all's place / the configs issued, by identity |
 | `screen-frame.tsx` / `screen-resource.tsx` / `screen-lookup.tsx` / `screen-home.tsx` / `screen-system.tsx` | request/response shape, shell, `guardedScreen` (a body's refused URL is a 400), `widgetContextOf` / list·detail·create·edit and their writes / the picker / dashboard / audit·search |
 | `list-request.ts` / `list-filters.ts` / `list-scope.ts` | URL ⇄ list request / operators per shape + the validator / row scope → scope → filters, `findRow`, `scopeCounts` |
 | `list.tsx` / `list-filter-bar.tsx` / `list-scope-tabs.tsx` / `renderers.tsx` | the list view / one GET form / tabs as links / computed cells |

package/README.md

@@ -86,12 +86,12 @@ closed `<details>` whose summary reads "N of M allowed".
 | `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, `singlePolicyAuthz(policy)` when one grant runs the whole
+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'`, and every control is a link or a native form: the pager
+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
@@ -377,6 +377,15 @@ 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](https://github.com/developerz-ai/ultimate/wiki/Admin-Dashboard#an-admin-page-in-your-own-shell).
+
 ### Splitting the admin across files
 
 `defineAdmin` takes **plain values** — `entities`, `db`, `resources`, `actions`, `jobs`, `pages`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "27.0.0",
+  "version": "27.2.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -34,20 +34,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.0.0",
-    "@ultimat3/ai": "27.0.0",
-    "@ultimat3/cache": "27.0.0",
-    "@ultimat3/core": "27.0.0",
-    "@ultimat3/db": "27.0.0",
-    "@ultimat3/entity": "27.0.0",
-    "@ultimat3/i18n": "27.0.0",
-    "@ultimat3/jobs": "27.0.0",
-    "@ultimat3/mcp": "27.0.0",
-    "@ultimat3/money": "27.0.0",
-    "@ultimat3/policy": "27.0.0",
-    "@ultimat3/query": "27.0.0",
-    "@ultimat3/render": "27.0.0",
-    "@ultimat3/schema": "27.0.0",
-    "@ultimat3/ui": "27.0.0"
+    "@ultimat3/action": "27.2.0",
+    "@ultimat3/ai": "27.2.0",
+    "@ultimat3/cache": "27.2.0",
+    "@ultimat3/core": "27.2.0",
+    "@ultimat3/db": "27.2.0",
+    "@ultimat3/entity": "27.2.0",
+    "@ultimat3/http": "27.2.0",
+    "@ultimat3/i18n": "27.2.0",
+    "@ultimat3/jobs": "27.2.0",
+    "@ultimat3/mcp": "27.2.0",
+    "@ultimat3/money": "27.2.0",
+    "@ultimat3/policy": "27.2.0",
+    "@ultimat3/query": "27.2.0",
+    "@ultimat3/render": "27.2.0",
+    "@ultimat3/schema": "27.2.0",
+    "@ultimat3/ui": "27.2.0"
   }
 }

package/src/actor.ts

@@ -21,6 +21,7 @@ export const adminActorFrom = (
     : {
         id: actor.id,
         roles: actor.roles,
+        ...(actor.permissions.length === 0 ? {} : { permissions: actor.permissions }),
         locale,
         timeZone,
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),

package/src/authz.ts

@@ -20,6 +20,12 @@ export interface AdminActor {
    */
   readonly orgId?: string;
   readonly roles?: readonly string[];
+  /**
+   * Direct grants — `Actor.permissions`, held with or without a role (a break-glass account, a
+   * staff session not yet enrolled in MFA). The request pipeline decides on roles AND these; the
+   * admin read roles only, so a route the pipeline opened answered a 403 screen.
+   */
+  readonly permissions?: readonly string[];
   /** BCP-47. Drives every `t()` call and every `Intl` format in the admin. */
   readonly locale?: string;
   /** IANA zone. The admin refuses to render a timestamp without one. */

package/src/batch-job.ts

@@ -39,6 +39,7 @@ const chunkInput = t.object({
   actor: t.object({
     id: t.string,
     roles: t.array(t.string),
+    permissions: t.optional(t.array(t.string)),
     orgId: t.optional(t.string),
     locale: t.optional(t.string),
     timeZone: t.optional(t.string),
@@ -58,6 +59,8 @@ export interface AdminBatchChunk {
   readonly actor: {
     readonly id: string;
     readonly roles: readonly string[];
+    /** Direct grants: an operator who holds the permission with no role runs the batch too. */
+    readonly permissions?: readonly string[] | undefined;
     readonly orgId?: string | undefined;
     readonly locale?: string | undefined;
     readonly timeZone?: string | undefined;
@@ -87,6 +90,7 @@ export async function runBatchChunk(chunk: AdminBatchChunk): Promise<readonly Ba
   const actor: AdminActor = {
     id: chunk.actor.id,
     roles: chunk.actor.roles,
+    ...(chunk.actor.permissions === undefined ? {} : { permissions: chunk.actor.permissions }),
     ...(chunk.actor.orgId === undefined ? {} : { orgId: chunk.actor.orgId }),
     ...(chunk.actor.locale === undefined ? {} : { locale: chunk.actor.locale }),
     ...(chunk.actor.timeZone === undefined ? {} : { timeZone: chunk.actor.timeZone }),
@@ -99,6 +103,7 @@ export async function runBatchChunk(chunk: AdminBatchChunk): Promise<readonly Ba
       actor: userActor({
         id: actor.id,
         roles: [...(actor.roles ?? [])],
+        permissions: [...(actor.permissions ?? [])],
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
       }),
     },
@@ -143,6 +148,7 @@ export const batchEnqueue =
       actor: {
         id: actor.id,
         roles: [...(actor.roles ?? [])],
+        ...(actor.permissions === undefined ? {} : { permissions: [...actor.permissions] }),
         ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
         ...(actor.locale === undefined ? {} : { locale: actor.locale }),
         ...(actor.timeZone === undefined ? {} : { timeZone: actor.timeZone }),

package/src/claim-route.ts

@@ -0,0 +1,146 @@
+// `claimAdminRoute()` — an app FILE serves one admin path in the catch-all's place, so the page
+// keeps the app's own shell and its islands (`hydrate`, budget and island bundle are a file
+// route's). The guard is not the app's: the route's gate, its `meta`, and a `load` that answers
+// through the SAME screen the catch-all serves (`screenFor`), unframed. `claims.ts` records the
+// config issued, and the route table accepts no other on that path.
+
+import { type HydrateStrategy, hasContext, isUltimateError } from '@ultimat3/core';
+import { setRedirect, useRequestHeaders } from '@ultimat3/http';
+import {
+  defineRoute,
+  type RouteBudget,
+  type RouteConfig,
+  type RouteNavigationMode,
+  routeStatusOf,
+  withStatus,
+} from '@ultimat3/render';
+import type { JSX } from 'solid-js';
+import type { AdminApp, AdminView } from './admin';
+import { issueClaim } from './claims';
+import type { CrudCtx } from './crud';
+import { AdminPagePathInvalidError } from './errors';
+import type { NavGroup } from './nav';
+import { adminRouteGuard, adminRouteMeta } from './route-config';
+import { screenFor } from './screens';
+
+/** What the app's own `load` is handed — called for every visitor the screen answered. */
+export interface AdminClaimLoadArgs {
+  readonly ctx: CrudCtx;
+  readonly params: Readonly<Record<string, string>>;
+  readonly url: string;
+  /** The body is the refusal (403), which carries its own `<h1>`. */
+  readonly denied: boolean;
+}
+
+export interface ClaimAdminRouteOptions<TApp> {
+  /** Absent: derived from the islands declared above the call, as for any route. */
+  readonly hydrate?: HydrateStrategy;
+  readonly budget?: RouteBudget;
+  readonly navigation?: RouteNavigationMode;
+  /**
+   * The app's half of the page data — its shell's role, locale and enrolment flag; a claimed
+   * dashboard's own figures. Runs AFTER the screen decided, the refused included: when `denied`
+   * it may read the visitor, never what the page guards. Answering `withStatus(404, …)` sets the
+   * page's status when the screen answered 200.
+   */
+  readonly load?: (args: AdminClaimLoadArgs) => TApp | Promise<TApp>;
+}
+
+/** What the claimed route's `load` hands the app's page component. */
+export interface AdminClaimData<TApp = undefined> {
+  /** The screen's body, decided and unframed: the page, or the refusal naming the permission. */
+  readonly body: JSX.Element;
+  readonly status: number;
+  readonly denied: boolean;
+  /** The route's title key; the body of a refusal carries its own heading. */
+  readonly titleKey: string;
+  /** The nav this actor may see — the admin's `navFor`. */
+  readonly nav: readonly NavGroup[];
+  /** What `options.load` returned; `undefined` without one. */
+  readonly app: TApp;
+}
+
+/**
+ * A `pages:` entry and the dashboard only. A generated screen posts its forms back to its own URL
+ * and re-renders a refused write there — in the admin's layout, from the catch-all — so a claim
+ * would split one screen across two shells.
+ */
+const CLAIMABLE: ReadonlySet<AdminView> = new Set<AdminView>(['page', 'dashboard']);
+
+/**
+ * The route config for the app file at `path` (the table's full path, base included). Call it
+ * BELOW the module's `island()` declarations, as `export const config = claimAdminRoute(…)`: its
+ * `defineRoute` drains them, which is how the page hydrates.
+ */
+export function claimAdminRoute<TApp = undefined>(
+  admin: AdminApp,
+  path: string,
+  options: ClaimAdminRouteOptions<TApp> = {},
+): RouteConfig<AdminClaimData<TApp>> {
+  const route = admin.routes.find((candidate) => candidate.path === path);
+  if (route === undefined) {
+    throw new AdminPagePathInvalidError({
+      path,
+      cause: 'is not a route this admin declares',
+      fix: `claimAdminRoute(admin, '<path>') with one of ${claimablePaths(admin)} — or add { path, titleKey, permissions, component } to pages: on defineAdmin()`,
+    });
+  }
+  if (!CLAIMABLE.has(route.view)) {
+    throw new AdminPagePathInvalidError({
+      path,
+      cause: `is the generated ${route.view} screen, which only the admin serves`,
+      fix: `claimAdminRoute(admin, '<path>') with one of ${claimablePaths(admin)}: a pages: entry or the dashboard`,
+    });
+  }
+  const screen = screenFor(admin, route);
+  const config = defineRoute<AdminClaimData<TApp>>({
+    render: 'ssr',
+    offline: 'network-only',
+    policy: adminRouteGuard(route),
+    meta: adminRouteMeta(route),
+    ...(options.hydrate === undefined ? {} : { hydrate: options.hydrate }),
+    ...(options.budget === undefined ? {} : { budget: options.budget }),
+    ...(options.navigation === undefined ? {} : { navigation: options.navigation }),
+    load: async ({ params, url }) => {
+      // The actor exactly as the catch-all resolves it: the admin's `auth.actor` over this request.
+      const ctx = await admin.requestCtx(new Request(url, { headers: requestHeaders() }));
+      const response = await screen({ ctx, params, url, method: 'GET', form: null, frame: 'none' });
+      if (response.kind === 'redirect') setRedirect(response.location, 303);
+      const body = response.kind === 'document' ? response.body : null;
+      const answered = response.kind === 'document' ? response.status : 200;
+      const denied = answered === 403;
+      const own = (await options.load?.({ ctx, params, url, denied })) as TApp;
+      const status = answered === 200 ? routeStatusOf(own) : answered;
+      const data: AdminClaimData<TApp> = {
+        body,
+        status,
+        denied,
+        titleKey: route.titleKey,
+        nav: admin.navFor(ctx),
+        app: own,
+      };
+      return status === 200 ? data : withStatus(status, data);
+    },
+  });
+  return issueClaim(route.path, config);
+}
+
+/**
+ * The headers of the request being rendered — the session cookie `auth.actor` reads. Outside a
+ * request (a test rendering the route) there are none, and the actor resolves as nobody: refused.
+ */
+function requestHeaders(): Headers {
+  if (!hasContext()) return new Headers();
+  try {
+    return useRequestHeaders();
+  } catch (error) {
+    if (isUltimateError(error) && error.code === 'X_NO_REQUEST') return new Headers();
+    throw error;
+  }
+}
+
+const claimablePaths = (admin: AdminApp): string =>
+  admin.routes
+    .filter((route) => CLAIMABLE.has(route.view))
+    .map((route) => route.path)
+    .join(', ');

package/src/claims.ts

@@ -0,0 +1,18 @@
+// The configs `claimAdminRoute` issued, each for the one path it was issued for. A leaf, read by
+// `route-config.ts` (the mount's `claimable`) and written by `claim-route.ts` alone — never
+// exported from the package: an app that could add a config here could put any route on an
+// admin path, guard or none.
+
+import type { RouteConfig } from '@ultimat3/render';
+
+/** By IDENTITY: a spread copy of an issued config — a swapped `load` — is not issued. */
+const issued = new WeakMap<object, string>();
+
+export function issueClaim<TConfig extends object>(path: string, config: TConfig): TConfig {
+  issued.set(config, path);
+  return config;
+}
+
+/** May `config` serve `path` in the admin's place? Only if it was issued for exactly that path. */
+export const claimable = (path: string, config: RouteConfig): boolean =>
+  issued.get(config) === path;

package/src/index.ts

@@ -123,6 +123,12 @@ export {
 } from './batch-job';
 export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
 export { BATCH_QUEUED_REASON } from './batch-queue';
+export {
+  type AdminClaimData,
+  type AdminClaimLoadArgs,
+  type ClaimAdminRouteOptions,
+  claimAdminRoute,
+} from './claim-route';
 export {
   type AdminUpdateOptions,
   adminCreate,

package/src/mcp.ts

@@ -311,6 +311,8 @@ const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
 const adminActorOf = (caller: McpCaller): AdminActor => ({
   id: caller.actor.id,
   roles: caller.actor.roles,
+  // Direct grants too: the pipeline decides on roles and `permissions` as one set.
+  ...(caller.actor.permissions.length === 0 ? {} : { permissions: caller.actor.permissions }),
   ...(caller.actor.orgId === undefined ? {} : { orgId: caller.actor.orgId }),
 });
 
@@ -453,7 +455,12 @@ export function adminMcp(opts: AdminMcpOptions): AppMcp {
       return actor === null
         ? null
         : {
-            actor: agentActor({ id: actor.id, roles: actor.roles ?? [], orgId: actor.orgId }),
+            actor: agentActor({
+              id: actor.id,
+              roles: actor.roles ?? [],
+              permissions: actor.permissions ?? [],
+              orgId: actor.orgId,
+            }),
             scopes: adminTokenScopes(actor.tokenScopes),
           };
     },

package/src/policy-bridge.ts

@@ -15,6 +15,7 @@ import {
 import {
   type AdminActor,
   type AdminAuthz,
+  type AdminAuthzQuery,
   type AdminDecision,
   type AdminSubject,
   adminAllowed,
@@ -31,7 +32,14 @@ const policyActor = (actor: AdminActor): Actor =>
   // `orgId` rides along, and its absence used to be silent: every admin decision was evaluated
   // with `actor.orgId === undefined`, so an org-scoped rule could not fire and a role-only rule
   // allowed a row from another tenant.
-  userActor({ id: actor.id, roles: actor.roles ?? [], orgId: actor.orgId });
+  // And the direct grants: `can()` reads roles and `permissions` as one set, exactly as the request
+  // pipeline does, so a permission held with no role opens the screen it opens the route for.
+  userActor({
+    id: actor.id,
+    roles: actor.roles ?? [],
+    permissions: actor.permissions ?? [],
+    orgId: actor.orgId,
+  });
 
 /**
  * `evaluate()`'s result is read structurally: the policy layer owns its own decision type,
@@ -99,34 +107,34 @@ const evaluated = (
  * whose rules read the row or the tenant passes `policyAuthz({ policies })` instead.
  */
 export function roleAuthz(): AdminAuthz {
-  return {
-    decide({ permission, actor, subject }): AdminDecision {
-      // Asked BEFORE `can()`, which throws on a name the registry lacks: a decision is an answer,
-      // and an undeclared permission is a refusal with its fix, never a 500 out of a nav render.
-      if (!isPermission(permission) || !isKnownPermission(permission)) {
-        return adminDenied(permission, 'admin.policy.missing', [
-          `"${permission}" is not a declared resource:verb permission`,
-          `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
-        ]);
-      }
-      // `can()` asserts the name against the registry `declareAdminPermissions` filled. The cast
-      // is the same one a route guard's bare string takes: the registry, not the type, is the check.
-      const own = evaluated(permission, can(permission as KnownPermission), actor, subject);
-      if (own.allowed) return own;
-      // The admin's implications, as `staticAuthz` applies them: a role granting `admin:destroy`
-      // holds `admin:write` and `admin:read` too. Without this the same grants answered two ways.
-      for (const implier of impliersOf(permission)) {
-        const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
-        if (carried.allowed) {
-          return adminAllowed(permission, carried.reason, [
-            ...carried.trace,
-            `${permission} is implied by ${implier}`,
-          ]);
-        }
-      }
-      return own;
-    },
-  };
+  return { decide: decideByRoleMap };
+}
+
+function decideByRoleMap({ permission, actor, subject }: AdminAuthzQuery): AdminDecision {
+  // Asked BEFORE `can()`, which throws on a name the registry lacks: a decision is an answer,
+  // and an undeclared permission is a refusal with its fix, never a 500 out of a nav render.
+  if (!isPermission(permission) || !isKnownPermission(permission)) {
+    return adminDenied(permission, 'admin.policy.missing', [
+      `"${permission}" is not a declared resource:verb permission`,
+      `fix: definePermissions(['${permission}']), then grant it to a role in defineRoles()`,
+    ]);
+  }
+  // `can()` asserts the name against the registry `declareAdminPermissions` filled. The cast
+  // is the same one a route guard's bare string takes: the registry, not the type, is the check.
+  const own = evaluated(permission, can(permission as KnownPermission), actor, subject);
+  if (own.allowed) return own;
+  // The admin's implications, as `staticAuthz` applies them: a role granting `admin:destroy`
+  // holds `admin:write` and `admin:read` too. Without this the same grants answered two ways.
+  for (const implier of impliersOf(permission)) {
+    const carried = evaluated(implier, can(implier as KnownPermission), actor, subject);
+    if (carried.allowed) {
+      return adminAllowed(permission, carried.reason, [
+        ...carried.trace,
+        `${permission} is implied by ${implier}`,
+      ]);
+    }
+  }
+  return own;
 }
 
 /**
@@ -149,20 +157,28 @@ export interface PolicyAuthzInput {
 }
 
 /**
- * Closed by default: a permission with no registered policy is denied, with the fix in the
- * trace. An admin that fails open is worse than an admin that fails visibly.
+ * The map REFINES, the role map GRANTS. A permission with a policy here is decided by it (a row
+ * or tenant rule, or a `deny` that closes what a role grants); one the map omits is decided by
+ * the role map and the actor's direct grants, exactly as `roleAuthz` and the request pipeline
+ * decide it. Still closed: a permission nobody declared is denied with the fix in the trace, and
+ * a declared one is denied by `can()` when neither a role nor the actor's direct grants hold it.
+ *
+ * Until 27.2.0 an omitted permission was denied outright, so the framework's own screens needed
+ * the same grant twice — `job:read` in `defineRoles` AND `'job:read': can('job:read')` here — and
+ * an app that wrote only the first had a jobs dashboard every operator was refused.
  */
 export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
   return {
-    decide({ permission, actor, subject }): AdminDecision {
-      const policy = input.policies[permission];
-      if (policy === undefined) {
-        return adminDenied(permission, 'admin.policy.missing', [
-          `no policy registered for "${permission}"`,
-          `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
-        ]);
+    decide(query): AdminDecision {
+      const policy = Object.hasOwn(input.policies, query.permission)
+        ? input.policies[query.permission]
+        : undefined;
+      if (policy !== undefined) {
+        return evaluated(query.permission, policy, query.actor, query.subject);
       }
-      return evaluated(permission, policy, actor, subject);
+      const decision = decideByRoleMap(query);
+      const by = `no policy mapped for "${query.permission}": decided by the role map`;
+      return { ...decision, trace: [by, ...decision.trace] };
     },
   };
 }

package/src/route-config.ts

@@ -11,6 +11,7 @@ import {
   registerMountedRoutes,
 } from '@ultimat3/render';
 import type { AdminRoute } from './admin';
+import { claimable } from './claims';
 import { AdminPageUnguardedError } from './errors';
 
 /** What `RouteDescriptor.file` reads for an admin route: the package, since no app file is one. */
@@ -23,16 +24,33 @@ export interface AdminRouteDefinition {
 }
 
 /**
- * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
- * which is the whole mechanism. The coarse gate is `permissions[0]` (always `admin:read`, put
- * there by `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per
- * request, in `crud.ts` for a resource screen and in `guardedScreen()` for every other one.
- * An empty list is refused here too: `render: 'ssr'` with no policy is a public dashboard.
+ * The coarse gate of `route`: `permissions[0]` (always `admin:read`, put there by
+ * `permissionsForOperation`/`pagePermissions`); the rest of the pair is decided per request, in
+ * `crud.ts` for a resource screen and in `guardedScreen()` for every other one. An empty list is
+ * refused: `render: 'ssr'` with no policy is a public dashboard.
  */
-export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+export function adminRouteGuard(route: AdminRoute): RouteGuard {
   const permission = route.permissions[0];
   if (permission === undefined) throw new AdminPageUnguardedError({ path: route.path });
-  const policy: RouteGuard = { permission };
+  return { permission };
+}
+
+/**
+ * Never indexed and never followed, whatever the screen answers — a list, a refusal, a 404: an
+ * admin URL in a search result is a row id handed to a crawler. The claimed route
+ * (`claim-route.ts`) is served under the same function.
+ */
+export const adminRouteMeta = (route: AdminRoute) => () => ({
+  title: t(route.titleKey),
+  robots: { index: false, follow: false },
+});
+
+/**
+ * The author never writes this `defineRoute` call, so the author cannot omit its `policy` —
+ * which is the whole mechanism.
+ */
+export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
+  const policy = adminRouteGuard(route);
   return {
     policy,
     config: defineRoute({
@@ -41,14 +59,13 @@ export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
       // every control on an admin screen is a link or a native form, so there is nothing to
       // hydrate. `never` is a REFUSAL and not just a default — an `island()` rendered on this
       // route throws `X_ISLAND_NOT_HYDRATED` (`@ultimat3/render`'s `island-collector.ts`), and no
-      // admin module declares one.
+      // admin module declares one. An app that needs one serves the path from its own file:
+      // `claimAdminRoute` (`claim-route.ts`).
       render: 'ssr',
       offline: 'network-only',
       hydrate: 'never',
       policy,
-      // Never indexed and never followed, whatever the screen answers — a list, a refusal, a 404:
-      // an admin URL in a search result is a row id handed to a crawler.
-      meta: () => ({ title: t(route.titleKey), robots: { index: false, follow: false } }),
+      meta: adminRouteMeta(route),
     }),
   };
 }
@@ -61,7 +78,9 @@ export function adminRouteDefinition(route: AdminRoute): AdminRouteDefinition {
  */
 export function mountAdminRoutes(basePath: string, routes: readonly AdminRoute[]): void {
   registerMountedRoutes(
-    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app' },
+    // `claimable`: the one way an app file serves a path of this table — a config
+    // `claimAdminRoute` issued for exactly that path. Anything else on it is X_ROUTE_DUPLICATE.
+    { key: basePath, by: 'defineAdmin', file: ADMIN_ROUTE_FILE, surface: 'app', claimable },
     routes.map((route) => ({
       path: route.path,
       config: adminRouteDefinition(route).config,

package/src/screen-frame.tsx

@@ -23,6 +23,12 @@ export interface AdminRouteRequest extends AdminPageProps {
   readonly method: 'GET' | 'POST';
   /** The parsed form. `null` on a GET; a POST with no fields is `{}`. */
   readonly form: Readonly<Record<string, unknown>> | null;
+  /**
+   * Who frames the body. Absent or `'admin'`: the admin's own layout. `'none'`: the body alone,
+   * for an app file that claimed the route (`claimAdminRoute`) and frames it in its own shell.
+   * The decision, the audit and the status are the screen's either way — only the wrapper differs.
+   */
+  readonly frame?: 'admin' | 'none';
 }
 
 export type AdminRouteResponse =
@@ -83,6 +89,7 @@ export function framed(
   body: JSX.Element,
   status = 200,
 ): AdminRouteResponse {
+  if (request.frame === 'none') return { kind: 'document', status, body };
   return {
     kind: 'document',
     status,