@ultimat3/admin 22.14.0 → 23.0.0

package/src/mcp-tools.ts

@@ -11,6 +11,7 @@ import { type AdminDecision, decideAll } from './authz';
 import { type CrudCtx, decideOperation, permissionsForOperation } from './crud';
 import type { AdminFieldType } from './fields';
 import type { AdminOperation } from './permissions';
+import type { AdminAction } from './registry';
 import type { AdminResource } from './resource';
 
 export type AdminToolKind = 'list' | 'read' | 'search' | 'create' | 'update' | 'delete' | 'action';
@@ -19,6 +20,8 @@ export interface AdminToolField {
   readonly name: string;
   readonly type: AdminFieldType;
   readonly required: boolean;
+  /** The argument is a LIST of `type`: the list tool's `where` is a list of predicates. */
+  readonly list?: true;
 }
 
 export interface AdminMcpTool {
@@ -49,11 +52,30 @@ const ID_FIELD: AdminToolField = { name: 'id', type: 'text', required: true };
  * description of the same contract. `mcp.ts` leaves an action tool's schema OPEN instead, so the
  * action's own validation is the one that decides.
  */
-const actionEnvelope = (destructive: boolean): readonly AdminToolField[] => [
+const actionEnvelope = (action: AdminAction): readonly AdminToolField[] => [
   { name: 'id', type: 'text', required: false },
-  ...(destructive ? [{ name: 'confirmation', type: 'text', required: true } as const] : []),
+  // A batch action is the SAME tool, given a list of rows instead of one: run once per row through
+  // the button's gate, answered with the counts the batch bar shows.
+  ...(action.batch === undefined
+    ? []
+    : [{ name: 'ids', type: 'text', required: false, list: true } as const]),
+  ...(action.destructive === true
+    ? [{ name: 'confirmation', type: 'text', required: true } as const]
+    : []),
 ];
 
+/** What an agent reads about when and over what an action runs — the schema cannot say it. */
+const actionDescription = (action: AdminAction): string =>
+  [
+    action.mcp?.description ?? `Run the ${action.name} action.`,
+    action.when === undefined
+      ? ''
+      : ' Applies only to some rows: a row it does not apply to is refused with X_ADMIN_ACTION_NOT_APPLICABLE.',
+    action.batch === undefined
+      ? ''
+      : ` Pass ids: [...] to run it once per row; the answer counts done, refused and failed${action.destructive === true ? ', and confirmation is "<entity>:<n> rows"' : ''}.`,
+  ].join('');
+
 const formFields = (resource: AdminResource): readonly AdminToolField[] =>
   resource.formFields.map((field) => ({
     name: field.name,
@@ -61,18 +83,40 @@ const formFields = (resource: AdminResource): readonly AdminToolField[] =>
     required: field.required,
   }));
 
+/**
+ * The list tool says what it filters by, because a schema cannot: `where` is a list of
+ * `{ field, op?, value }` and the fields and scopes are this resource's own. The same names the
+ * list screen's URL takes — one grammar, two transports.
+ */
+const listDescription = (resource: AdminResource): string => {
+  const filters = resource.filters.map((field) => field.name);
+  const scopes = resource.scopes.map((scope) => scope.name);
+  return [
+    `List ${resource.name} rows, cursor-paginated.`,
+    filters.length === 0
+      ? ''
+      : ` where: [{ field, op?, value }] over ${filters.join(', ')}; op defaults per field.`,
+    scopes.length === 0 ? '' : ` scope: one of ${scopes.join(', ')}.`,
+  ].join('');
+};
+
 function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | null {
   switch (op) {
     case 'list':
       return {
         name: `admin.${resource.name}.list`,
         kind: 'list',
-        description: `List ${resource.name} rows, cursor-paginated, newest first.`,
+        description: listDescription(resource),
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'list'),
+        permissions: permissionsForOperation(resource.permission, 'list'),
         destructive: false,
-        input: [CURSOR_FIELD, { name: 'limit', type: 'number', required: false }],
+        input: [
+          CURSOR_FIELD,
+          { name: 'limit', type: 'number', required: false },
+          { name: 'scope', type: 'text', required: false },
+          { name: 'where', type: 'json', required: false, list: true },
+        ],
       };
     case 'detail':
       return {
@@ -81,7 +125,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Read one ${resource.name} row by id.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'detail'),
+        permissions: permissionsForOperation(resource.permission, 'detail'),
         destructive: false,
         input: [ID_FIELD],
       };
@@ -92,7 +136,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Create a ${resource.name} row. Validated by the entity's schema.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'create'),
+        permissions: permissionsForOperation(resource.permission, 'create'),
         destructive: false,
         input: formFields(resource),
       };
@@ -103,7 +147,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Update fields of one ${resource.name} row.`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'update'),
+        permissions: permissionsForOperation(resource.permission, 'update'),
         destructive: false,
         input: [ID_FIELD, ...formFields(resource)],
       };
@@ -114,7 +158,7 @@ function toolFor(resource: AdminResource, op: AdminOperation): AdminMcpTool | nu
         description: `Delete one ${resource.name} row. Requires confirmation "<entity>:<id>".`,
         entity: resource.name,
         action: null,
-        permissions: permissionsForOperation(resource.name, 'delete'),
+        permissions: permissionsForOperation(resource.permission, 'delete'),
         destructive: true,
         input: [ID_FIELD, { name: 'confirmation', type: 'text', required: true }],
       };
@@ -154,12 +198,12 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
         tool: {
           name: `admin.action.${action.name}`,
           kind: 'action',
-          description: action.mcp?.description ?? `Run the ${action.name} action.`,
+          description: actionDescription(action),
           entity: action.entity ?? null,
           action: action.name,
           permissions: permissionsForAction(action),
           destructive: action.destructive === true,
-          input: actionEnvelope(action.destructive === true),
+          input: actionEnvelope(action),
         },
         gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
       });
@@ -189,12 +233,12 @@ function toolGates(app: AdminApp): readonly ToolGate[] {
       tool: {
         name: `admin.action.${action.name}`,
         kind: 'action',
-        description: action.mcp?.description ?? `Run the ${action.name} action.`,
+        description: actionDescription(action),
         entity: null,
         action: action.name,
         permissions: permissionsForAction(action),
         destructive: action.destructive === true,
-        input: actionEnvelope(action.destructive === true),
+        input: actionEnvelope(action),
       },
       gate: (ctx) => decideAction(action, ctx.actor, ctx.authz),
     });

package/src/mcp.ts

@@ -22,8 +22,11 @@ import {
   type ToolArgs,
 } from '@ultimat3/mcp';
 import { invokeAdminAction } from './action-gate';
+import { invokeRowAction } from './action-row';
 import type { AdminApp } from './admin';
 import type { AdminActor } from './authz';
+import { batchPlan, runAdminBatch } from './batch';
+import { batchEnqueue } from './batch-job';
 import {
   adminCreate,
   adminDestroy,
@@ -33,11 +36,13 @@ import {
   type CrudCtx,
   type CrudResult,
 } from './crud';
+import { AdminFilterInvalidError } from './errors';
 import type { AdminFieldType } from './fields';
+import { type AskedFilter, checkedFilter } from './list-filters';
 import { type AdminMcpTool, adminMcpTools, adminToolCatalog } from './mcp-tools';
 import type { AdminAction, AdminRow } from './registry';
-import { repoOf } from './resource';
 import { adminSearch } from './search';
+import type { ValidationIssue } from './validate';
 
 export type McpInput = Readonly<Record<string, unknown>>;
 
@@ -63,6 +68,22 @@ const withoutKeys = (input: McpInput, keys: readonly string[]): Record<string, u
   return out;
 };
 
+/** The `where` argument as a list of asked filters; anything else in it is refused by name. */
+const askedFilters = (where: unknown): readonly AskedFilter[] => {
+  if (where === undefined || where === null) return [];
+  const list: readonly unknown[] = Array.isArray(where) ? where : [where];
+  return list.map((one) => {
+    const bag = (typeof one === 'object' && one !== null ? one : {}) as Record<string, unknown>;
+    const op = bag['op'];
+    return {
+      // A predicate with no `field` names the empty one, which no resource derives.
+      field: typeof bag['field'] === 'string' ? bag['field'] : '',
+      ...(typeof op === 'string' ? { op } : {}),
+      value: bag['value'],
+    };
+  });
+};
+
 const actionByName = (app: AdminApp, name: string): AdminAction | undefined =>
   [...app.resources.flatMap((resource) => resource.actions), ...app.globalActions].find(
     (action) => action.name === name,
@@ -110,46 +131,77 @@ async function dispatch(
     if (action === undefined) {
       return { ok: false, error: 'X_ADMIN_TOOL_FORBIDDEN', reason: 'action is not registered' };
     }
-    const id = str(input, 'id');
-    // The row a row-level rule decides about, loaded through the resource that OWNS the action —
-    // what the UI's action button does. Without it the subject carried an id and no row, so an
-    // ownership rule could never allow. `null` for a row that does not exist: no evidence of
-    // permission, same contract as an action's `row:` loader. A global action names no resource.
     const owner = app.resources.find((resource) => resource.actions.includes(action));
-    const row =
-      owner === undefined || id === '' ? undefined : ((await repoOf(owner).find(id)) ?? null);
-    const result = await invokeAdminAction({
-      action,
-      input: withoutKeys(input, ['confirmation']),
-      actor: ctx.actor,
-      authz: ctx.authz,
-      audit: ctx.audit,
-      requestId: ctx.requestId,
-      subject: {
-        ...(action.entity === undefined ? {} : { entity: action.entity }),
-        ...(id === '' ? {} : { id }),
-        ...(row === undefined ? {} : { row }),
-      },
-      // The agent must echo the token, exactly as the UI makes an operator type it — and the gate
-      // derives the token it expects from the entity and `subject.id` above.
-      confirmation: str(input, 'confirmation'),
-    });
-    return result.ok
-      ? { ok: true, data: result.value }
-      : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    const own = withoutKeys(input, ['id', 'ids', 'confirmation']);
+    const confirmation = str(input, 'confirmation');
+    // `ids`: the same tool as a batch — the bar's own path, row by row through the gate.
+    if (owner !== undefined && action.batch !== undefined && Array.isArray(input['ids'])) {
+      const ids = (input['ids'] as readonly unknown[]).filter(
+        (one): one is string => typeof one === 'string',
+      );
+      const result = await runAdminBatch({
+        resource: owner,
+        action,
+        ctx,
+        selection: { kind: 'ids', ids },
+        input: own,
+        confirmation,
+        ...(batchPlan(action) === null ? {} : { enqueue: batchEnqueue(app.basePath) }),
+      });
+      if (result.ok) return { ok: true, data: result };
+      if (result.kind === 'invalid') return invalidIssues(result.issues);
+      return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+    }
+    const id = str(input, 'id');
+    // The row a row-level rule — and the action's own `when` — decides about, loaded through the
+    // resource that OWNS the action: what the UI's button does. A global action names no row.
+    const result =
+      owner !== undefined && id !== ''
+        ? await invokeRowAction({ resource: owner, action, id, ctx, input: own, confirmation })
+        : await invokeAdminAction({
+            action,
+            input: { ...own, ...(id === '' ? {} : { id }) },
+            actor: ctx.actor,
+            authz: ctx.authz,
+            audit: ctx.audit,
+            requestId: ctx.requestId,
+            subject: {
+              ...(action.entity === undefined ? {} : { entity: action.entity }),
+              ...(id === '' ? {} : { id }),
+            },
+            // The agent must echo the token, exactly as the UI makes an operator type it.
+            confirmation,
+          });
+    if (result.ok) return { ok: true, data: result.value };
+    if (result.kind === 'not-applicable') {
+      return { ok: false, error: result.error.code, reason: result.error.cause };
+    }
+    if (result.kind === 'invalid') return invalidIssues(result.issues);
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
   }
 
   const resource = app.resource(tool.entity ?? '');
   switch (tool.kind) {
     case 'list': {
       const limit = num(input, 'limit');
-      const result = await adminList(resource, ctx, {
-        cursor: str(input, 'cursor'),
-        ...(limit === undefined ? {} : { limit }),
-      });
-      return result.ok
-        ? { ok: true, data: result.page }
-        : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+      const scope = str(input, 'scope');
+      try {
+        // `where` through the same validator a URL's `f.<field>` passes, and the scope by name:
+        // an agent filters by exactly what an operator can, and the resource's row scope rides
+        // the read inside `adminList` whatever the agent sends.
+        const result = await adminList(resource, ctx, {
+          cursor: str(input, 'cursor'),
+          ...(limit === undefined ? {} : { limit }),
+          ...(scope === '' ? {} : { scope }),
+          filters: askedFilters(input['where']).map((asked) => checkedFilter(resource, asked)),
+        });
+        return result.ok
+          ? { ok: true, data: result.page }
+          : { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+      } catch (error) {
+        if (!(error instanceof AdminFilterInvalidError)) throw error;
+        return { ok: false, error: error.code, reason: error.cause };
+      }
     }
     case 'read':
       return crudResult(await adminDetail(resource, ctx, str(input, 'id')));
@@ -166,11 +218,23 @@ async function dispatch(
   }
 }
 
+/** The schema's issues, as the one string an agent's result carries. */
+const invalidIssues = (issues: readonly ValidationIssue[]): AdminToolResult => ({
+  ok: false,
+  error: 'X_ADMIN_INVALID',
+  reason: JSON.stringify(issues),
+});
+
 function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
   if (result.ok) return { ok: true, data: result.row };
-  return result.kind === 'denied'
-    ? { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason }
-    : { ok: false, error: 'X_ADMIN_INVALID', reason: JSON.stringify(result.issues) };
+  if (result.kind === 'denied') {
+    return { ok: false, error: 'X_ADMIN_DENIED', reason: result.decision.reason };
+  }
+  // No row by that id — or none this caller's row scope lets them see, which reads the same.
+  if (result.kind === 'missing') {
+    return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
+  }
+  return invalidIssues(result.issues);
 }
 
 export interface AdminMcpOptions {
@@ -195,6 +259,9 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
   json: 'object',
   relation: 'string',
   file: 'string',
+  // A sealed column travels as the text an agent sends. It is in no tool schema today — the
+  // CRUD tools are built from `formFields`, which never holds one.
+  secret: 'string',
 };
 
 /**
@@ -210,7 +277,10 @@ const JSON_TYPE: Readonly<Record<AdminFieldType, NonNullable<JsonSchema['type']>
 const inputSchema = (tool: AdminMcpTool): JsonSchema => ({
   type: 'object',
   properties: Object.fromEntries(
-    tool.input.map((field) => [field.name, { type: JSON_TYPE[field.type] }]),
+    tool.input.map((field) => {
+      const one = { type: JSON_TYPE[field.type] };
+      return [field.name, field.list === true ? { type: 'array', items: one } : one];
+    }),
   ),
   required: tool.input.filter((field) => field.required).map((field) => field.name),
   additionalProperties: tool.kind === 'action',

package/src/mounts.ts

@@ -0,0 +1,44 @@
+// Which admins this process declared, by base path — what a host reads to MOUNT them. Kept on the
+// global symbol registry rather than in a module variable so the host can ask "did this app
+// declare an admin?" WITHOUT importing this package: importing it loads every screen, and an app
+// with no admin must not pay for one (axiom 6).
+
+import type { AdminApp } from './admin';
+
+/** The global key. `@ultimat3/cli`'s `runtime-admin.ts` restates the string; a test holds them equal. */
+export const ADMIN_MOUNTS: symbol = Symbol.for('ultimate.admin.mounts');
+
+type Mounts = Map<string, AdminApp>;
+
+const mounts = (): Mounts => {
+  const scope = globalThis as { [key: symbol]: unknown };
+  const held = scope[ADMIN_MOUNTS];
+  if (held instanceof Map) return held as Mounts;
+  const created: Mounts = new Map();
+  scope[ADMIN_MOUNTS] = created;
+  return created;
+};
+
+/**
+ * Called by `defineAdmin()`. Keyed by base path and last-wins: `x dev` re-evaluates the module
+ * that declares the admin when it changes, and the admin a request then meets has to be the one
+ * the author just saved.
+ */
+export function registerAdminMount(app: AdminApp): void {
+  mounts().set(app.basePath, app);
+}
+
+/** Every declared admin, in declaration order. */
+export function adminMounts(): readonly AdminApp[] {
+  return [...mounts().values()];
+}
+
+/** The admin declared at `basePath` NOW, or `undefined`. Read per request, never captured. */
+export function adminMountAt(basePath: string): AdminApp | undefined {
+  return mounts().get(basePath);
+}
+
+/** Test seam; a running process never forgets an admin it declared. */
+export function clearAdminMounts(): void {
+  mounts().clear();
+}

package/src/page-guard.tsx

@@ -1,13 +1,14 @@
-// The wrapper that makes a custom page's authz unskippable. `routes.ts` never hands the router
-// the author's component — it hands this one, which asks the SAME `decideAll` every CRUD call
-// and every nav item asks, audits the refusal, and only then calls the author's code.
+// What a refused screen renders and the audit entry it leaves. The wrapper that DECIDES is
+// `guardedScreen()` in `screen-frame.tsx`: `routes.ts` never hands a host the author's component
+// — it hands that screen, which asks the SAME `decideAll` every CRUD call and every nav item
+// asks, audits the refusal through this file, and only then calls the author's code.
 
 import { t } from '@ultimat3/i18n';
 import type { JSX } from 'solid-js';
-import type { AdminRoute } from './admin';
+import styles from './admin.module.scss';
 import { deniedDraft } from './audit';
-import { type AdminDecision, decideAll } from './authz';
-import type { AdminPageComponent, AdminPageProps } from './pages';
+import type { AdminDecision } from './authz';
+import type { CrudCtx } from './crud';
 
 /**
  * The refusal, rendered as the page. Not a redirect and not a 404: an operator who is missing a
@@ -21,7 +22,7 @@ export function AdminPageDenied(props: {
   return (
     <section class="x-admin-denied" role="alert">
       <h1>{t(props.titleKey)}</h1>
-      <p>
+      <p class={styles['refusal']}>
         {t('admin.denied.body', {
           permission: props.decision.permission,
           reason: props.decision.reason,
@@ -32,27 +33,23 @@ export function AdminPageDenied(props: {
 }
 
 /**
- * Wrap once, at route-table build time. The author's component is never reachable from
- * `adminRoutes()`, so "the page that forgot its policy line" has nowhere left to exist.
+ * The audit entry of a refused SCREEN. The page is the subject, so its path is what the row
+ * names — there is no entity and no row id to key a refused screen by. One writer, so a custom
+ * page and a generated form's GET leave the same entry.
  */
-export function guardedPage(route: AdminRoute, component: AdminPageComponent): AdminPageComponent {
-  return async (props: AdminPageProps): Promise<JSX.Element> => {
-    const decision = decideAll(props.ctx.authz, route.permissions, props.ctx.actor);
-    if (!decision.allowed) {
-      // The page IS the subject here, so its path is what the audit row names — there is no
-      // entity and no row id to key a refused screen by.
-      await props.ctx.audit.append(
-        deniedDraft({
-          requestId: props.ctx.requestId,
-          actor: props.ctx.actor,
-          operation: 'page',
-          kind: 'operation',
-          entity: route.path,
-          decision,
-        }),
-      );
-      return <AdminPageDenied titleKey={route.titleKey} decision={decision} />;
-    }
-    return component(props);
-  };
+export async function auditRefusal(
+  ctx: CrudCtx,
+  path: string,
+  decision: AdminDecision,
+): Promise<void> {
+  await ctx.audit.append(
+    deniedDraft({
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: 'page',
+      kind: 'operation',
+      entity: path,
+      decision,
+    }),
+  );
 }

package/src/policy-bridge.ts

@@ -3,8 +3,24 @@
 // policies and the dashboard — and no second authz implementation can grow next to it.
 
 import { type Actor, userActor } from '@ultimat3/core';
-import { definePermissions, evaluate, type Policy } from '@ultimat3/policy';
-import { type AdminActor, type AdminAuthz, type AdminDecision, allowed, denied } from './authz';
+import {
+  can,
+  definePermissions,
+  evaluate,
+  isKnownPermission,
+  type KnownPermission,
+  type Permission,
+  type Policy,
+} from '@ultimat3/policy';
+import {
+  type AdminActor,
+  type AdminAuthz,
+  type AdminDecision,
+  type AdminSubject,
+  allowed,
+  denied,
+  impliersOf,
+} from './authz';
 import { ADMIN_PERMISSIONS } from './permissions';
 
 /** The admin's own permission set, registered with the policy layer at import time. */
@@ -27,15 +43,104 @@ const policyActor = (actor: AdminActor): Actor =>
 function readDecision(permission: string, result: unknown): AdminDecision {
   const bag = (typeof result === 'object' && result !== null ? result : {}) as {
     allowed?: unknown;
-    reason?: unknown;
+    decision?: unknown;
     trace?: unknown;
   };
+  // The reason lives on the evaluation's `decision`, not beside `allowed`. It was read off the top
+  // level, where no evaluation has ever carried one, so every refusal an operator read said
+  // `admin.policy.evaluated` — the same string whichever rule refused them.
+  const inner = (typeof bag.decision === 'object' && bag.decision !== null ? bag.decision : {}) as {
+    reason?: unknown;
+  };
   const verdict = result === true || bag.allowed === true;
-  const reason = typeof bag.reason === 'string' ? bag.reason : 'admin.policy.evaluated';
+  const reason = typeof inner.reason === 'string' ? inner.reason : 'admin.policy.evaluated';
   const trace = Array.isArray(bag.trace) ? bag.trace.map((line) => String(line)) : [];
   return verdict ? allowed(permission, reason, trace) : denied(permission, reason, trace);
 }
 
+/** `resource:verb` — the only shape `can()` takes. Anything else is denied, never thrown. */
+const isPermission = (value: string): value is Permission => /^[^:]+:[^:]+$/.test(value);
+
+/**
+ * Declare the permissions an admin DERIVES — `<entity>:read|write|delete`, a page's, an action's —
+ * so `can()` knows them. Granting them stays the app's: a role map that names none of these
+ * refuses every screen. Idempotent, and this file's because it is the one that speaks to
+ * `@ultimat3/policy`.
+ */
+export function declareAdminPermissions(permissions: readonly string[]): void {
+  definePermissions(permissions.filter(isPermission));
+}
+
+const evaluated = (
+  permission: string,
+  policy: Policy,
+  actor: AdminActor,
+  subject: AdminSubject | undefined,
+): AdminDecision => {
+  // `EvaluateArgs` carries exactly one payload. An admin subject with no action input IS
+  // that payload: a row-level rule has nothing but the entity and id to decide on.
+  const payload = subject?.input ?? subject;
+  // `row` is passed through only when the surface LOADED one. Omitting it and passing
+  // `row: undefined` are different facts to `evaluate`, and a rule that reads `row` must see
+  // `null` — "no row was loaded" — rather than a value the admin invented from `input`.
+  const row = subject === undefined || !('row' in subject) ? undefined : { row: subject.row };
+  return readDecision(
+    permission,
+    evaluate(policy, { actor: policyActor(actor), input: payload, ...row }),
+  );
+};
+
+/**
+ * The default authz: the app's ROLE MAP decides. Every permission the admin asks about is
+ * `can(permission)` — "does a role this actor holds grant it" — so an app with a `defineRoles()`
+ * call has a working, closed admin with no permission → policy table to keep in step. An app
+ * 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 denied(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 allowed(permission, carried.reason, [
+            ...carried.trace,
+            `${permission} is implied by ${implier}`,
+          ]);
+        }
+      }
+      return own;
+    },
+  };
+}
+
+/**
+ * ONE policy answers every gate the admin asks — "whoever may run the app may run its admin".
+ * The shape a small app starts in: a single grant its role map already has, with no table of
+ * per-entity permissions to keep in step as entities are added. The pair is still asked
+ * (`admin:write` then `posts:write`), each is still audited under its own name, and the day a
+ * view-only operator is needed this becomes `roleAuthz()` or `policyAuthz({ policies })`.
+ */
+export function singlePolicyAuthz(policy: Policy): AdminAuthz {
+  return {
+    decide: ({ permission, actor, subject }): AdminDecision =>
+      evaluated(permission, policy, actor, subject),
+  };
+}
+
 export interface PolicyAuthzInput {
   /** Permission name → the policy that decides it. `describeActions()` supplies these. */
   readonly policies: Readonly<Record<string, Policy>>;
@@ -55,17 +160,7 @@ export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
           `fix: definePermissions({ '${permission}': … }) or can('${permission}') on the action`,
         ]);
       }
-      // `EvaluateArgs` carries exactly one payload. An admin subject with no action input IS
-      // that payload: a row-level rule has nothing but the entity and id to decide on.
-      const payload = subject?.input ?? subject;
-      // `row` is passed through only when the surface LOADED one. Omitting it and passing
-      // `row: undefined` are different facts to `evaluate`, and a rule that reads `row` must see
-      // `null` — "no row was loaded" — rather than a value the admin invented from `input`.
-      const row = subject === undefined || !('row' in subject) ? undefined : { row: subject.row };
-      return readDecision(
-        permission,
-        evaluate(policy, { actor: policyActor(actor), input: payload, ...row }),
-      );
+      return evaluated(permission, policy, actor, subject);
     },
   };
 }