@ultimat3/admin 2.0.0 → 4.0.0

package/src/dev/panel-db.ts

@@ -4,12 +4,19 @@
 
 import { isUltimateError } from '@ultimat3/core';
 import { assertReadOnlyQuery } from '@ultimat3/mcp';
+import { DevSourceUnavailableError } from '../errors';
 import type { DriftFact, SqlResult, TableFact } from './facts';
 import type { DevPanel } from './panel';
 
 export interface DbPanelData {
   readonly tables: readonly TableFact[];
-  readonly drift: readonly DriftFact[];
+  /**
+   * `null` when no host wired the check — NOT `[]`. Drift is the entities against the database,
+   * so it needs the connection this process may not have, and an empty list reads as "the schema
+   * matches", which is the one answer a panel that never looked has not earned. The same
+   * distinction `panel-timeline.ts` draws for `nPlusOne` and `panel-live.ts` for its subscribers.
+   */
+  readonly drift: readonly DriftFact[] | null;
   readonly sql: string | null;
   readonly result: SqlResult | null;
   /** Set when a statement was refused; the panel shows it instead of a result grid. */
@@ -95,7 +102,16 @@ export const dbPanel: DevPanel<DbPanelData> = {
   titleKey: 'dev.panel.db.title',
   questionKey: 'dev.panel.db.question',
   async data(sources, params): Promise<DbPanelData> {
-    const [tables, drift] = await Promise.all([sources.tables(), sources.drift()]);
+    // The drift half degrades on its own: a host with no drift check must still get the table
+    // list and the SQL box. Only `DevSourceUnavailableError` is caught — a checker that ran and
+    // FAILED is a diagnostic, and reaches `panelPayload` with its code and its fix.
+    const [tables, drift] = await Promise.all([
+      sources.tables(),
+      sources.drift().catch((error: unknown) => {
+        if (!(error instanceof DevSourceUnavailableError)) throw error;
+        return null;
+      }),
+    ]);
     const sql = params.get('sql');
     if (sql === null || sql.trim() === '') {
       return { tables, drift, sql: null, result: null, refused: null, readOnly: true };

package/src/dev/panel-routes.ts

@@ -1,6 +1,6 @@
 // Panel: Routes.
-// Kills: "which handler serves this?" — the route table with render mode, offline strategy,
-// budget, and whether the route declares meta.
+// Kills: "which handler serves this?" — the route table with render mode, offline strategy
+// and budget.
 
 import type { RouteFact } from './facts';
 import type { DevPanel } from './panel';
@@ -9,7 +9,9 @@ export interface RoutesPanelData {
   readonly routes: readonly RouteFact[];
   /** Counts per render mode: an app that is all `ssr` has a caching problem to find. */
   readonly byRenderMode: Readonly<Record<string, number>>;
-  readonly missingMeta: readonly string[];
+  // No `missingMeta`. `defineRoute()` refuses a route without a `meta` function, so the list had
+  // no member it could ever hold — and it was published from a `RouteFact.hasMeta` that read a
+  // key no descriptor has, which made it name EVERY route instead. See `RouteFact` in `facts.ts`.
   readonly overBudget: readonly string[];
 }
 
@@ -34,7 +36,6 @@ export const routesPanel: DevPanel<RoutesPanelData> = {
     return {
       routes: [...routes].sort((a, b) => a.path.localeCompare(b.path)),
       byRenderMode,
-      missingMeta: routes.filter((route) => !route.hasMeta).map((route) => route.path),
       overBudget: routes
         .filter((route) => kb(route.budget.js) > BUDGET_LIMIT_KB)
         .map((route) => route.path),

package/src/dev/panel.ts

@@ -2,6 +2,7 @@
 // draws — and because `data()` returns plain JSON, `--json` and the rendered tab are the
 // same facts by construction.
 
+import { renderThrowable, stringField } from '@ultimat3/core';
 import type { DevSources } from './facts';
 
 export interface DevPanel<Data = unknown> {
@@ -25,12 +26,6 @@ export type PanelPayload =
       readonly error: { readonly code: string; readonly cause: string; readonly fix: string };
     };
 
-interface ErrorFields {
-  readonly code?: unknown;
-  readonly cause?: unknown;
-  readonly fix?: unknown;
-}
-
 /**
  * A panel whose source is not wired must say so in the panel, with the fix line — the same
  * payload the CLI prints. A blank tab would read as "nothing is happening".
@@ -43,19 +38,18 @@ export async function panelPayload(
   try {
     return { panel: panel.key, ok: true, data: await panel.data(sources, params) };
   } catch (error) {
-    const fields = (error ?? {}) as ErrorFields;
+    // Core's total readers, not `String(error)` and a raw property read. This catch owes its
+    // caller a `/_x` RESPONSE: `String(Object.create(null))` throws, and so does a getter or a
+    // Proxy trap on `error.code` — either turns a rendered failure panel into an unhandled
+    // rejection on the request. `stringField` answers `undefined` for absent, wrong type and
+    // threw alike, which is what every branch below already meant.
     return {
       panel: panel.key,
       ok: false,
       error: {
-        code: typeof fields.code === 'string' ? fields.code : 'X_NOT_IMPLEMENTED',
-        cause:
-          typeof fields.cause === 'string'
-            ? fields.cause
-            : error instanceof Error
-              ? error.message
-              : String(error),
-        fix: typeof fields.fix === 'string' ? fields.fix : 'x dev --help',
+        code: stringField(error, 'code') ?? 'X_NOT_IMPLEMENTED',
+        cause: stringField(error, 'cause') ?? renderThrowable(error),
+        fix: stringField(error, 'fix') ?? 'x dev --help',
       },
     };
   }

package/src/errors.ts

@@ -21,6 +21,10 @@ export const ADMIN_OWNED_ERROR_CODES = [
   // screen, is a defect the author must never be able to deploy.
   'X_ADMIN_PAGE_UNGUARDED',
   'X_ADMIN_PAGE_PATH_INVALID',
+  // `AdminAction.name` addresses one handler in three places at once — the MCP tool name, the
+  // default label key, and `callAdminTool`'s lookup. Two actions sharing it is refused where the
+  // admin is DECLARED, so an app that never wires MCP still cannot ship the ambiguity.
+  'X_ADMIN_ACTION_DUPLICATE',
 ] as const;
 
 /**
@@ -48,6 +52,7 @@ export const ADMIN_ERROR_TITLES: Readonly<Record<AdminOwnedErrorCode, string>> =
   X_ADMIN_INVALID: "an admin tool's arguments failed the resource schema",
   X_ADMIN_PAGE_UNGUARDED: 'a custom admin page declared no permissions',
   X_ADMIN_PAGE_PATH_INVALID: 'a custom admin page has an unusable or already-taken path',
+  X_ADMIN_ACTION_DUPLICATE: 'two admin actions share one name',
 };
 
 // One unconditional call, so a second package claiming one of admin's codes throws
@@ -90,6 +95,25 @@ export class AdminFieldUnsupportedError extends UltimateError {
   }
 }
 
+/**
+ * Two registered actions carry one `name`. Refused at `defineAdmin`, not at the first call: the
+ * name is the MCP tool name, the default label key AND the key `callAdminTool` resolves a handler
+ * by, so a collision is a call that succeeds against the wrong action and reports nothing.
+ */
+export class AdminActionDuplicateError extends UltimateError {
+  constructor(input: { name: string; entities: readonly string[] }) {
+    const where = input.entities.length > 0 ? input.entities.join(' and ') : 'the global toolbar';
+    super({
+      code: 'X_ADMIN_ACTION_DUPLICATE',
+      cause: `two admin actions are named "${input.name}" (on ${where}); an action name addresses one handler`,
+      // The convention the framework's own examples already follow, made into the instruction:
+      // an entity-qualified name is unique by construction.
+      fix: `rename one in defineAdmin's actions — name: '<entity>.${input.name}' — so "${input.name}" belongs to one of them`,
+      docs: docsFor('X_ADMIN_ACTION_DUPLICATE'),
+    });
+  }
+}
+
 /**
  * An action reached the admin without a policy — the button would be an open door.
  *

package/src/fields.ts

@@ -84,6 +84,22 @@ export function widgetFor(type: AdminFieldType): AdminWidget {
  * Every kind `@ultimat3/entity` can put on a column, and nothing else: a name that no column
  * builder emits would be a widget nobody can reach. `text` is the entry the length rule below
  * then refines.
+ *
+ * The kinds an EXISTING schema brings (`bigint()`, `decimal()`, `date()`, `arrayOf()`) each map to
+ * the widget that survives a round trip of the value the column itself produces, which is not
+ * always the widget the Postgres type suggests:
+ *
+ * | kind | field type | why not the obvious one |
+ * |---|---|---|
+ * | `numeric` | `text` | the row value is the exact decimal STRING, and `number-input` renders anything that is not a JS number as null — a blanked field that saves the blank back |
+ * | `bigint` | `text` | same reason, and it shipped as `number` before `bigint()` existed: the row value is decimal digits, because a JS `bigint` is what `JSON.stringify` throws on and a `number` loses everything past 2^53 — the range a legacy `int8` key lives in |
+ * | `date` | `date` | a calendar date has no zone, so it takes the `precision: 'date'` branch (`<input type="date">`) rather than the instant one |
+ * | `array` | `json` | `String(['a,b'])` and `String(['a','b'])` are the same string, and what a text input posts back is not an array at all |
+ *
+ * `bytea` is deliberately ABSENT. The `file` widget's value is a storage reference (`{ url, name }`
+ * — see `uploadValue`), and the `Uint8Array` a `bytes()` column puts on the row is not one, so
+ * mapping it would move the same refusal from derive time, where the fix names the edit, to every
+ * render of every row. There is no `vector` row for the same reason there is no vector column.
  */
 const FIELD_TYPE_BY_COLUMN_KIND: Readonly<Record<string, AdminFieldType>> = {
   uuid: 'text',
@@ -91,9 +107,12 @@ const FIELD_TYPE_BY_COLUMN_KIND: Readonly<Record<string, AdminFieldType>> = {
   char: 'text',
   boolean: 'boolean',
   integer: 'number',
-  bigint: 'number',
+  bigint: 'text',
+  numeric: 'text',
   timestamptz: 'timestamptz',
+  date: 'date',
   jsonb: 'json',
+  array: 'json',
   money: 'money',
 };
 
@@ -146,6 +165,26 @@ export function sortable(type: AdminFieldType, column: AdminColumnFacts): boolea
   return column.index || column.unique || column.primaryKey;
 }
 
-export function searchable(type: AdminFieldType): boolean {
-  return type === 'text' || type === 'textarea';
+/**
+ * The column kinds Postgres will accept a `LIKE` against. MEASURED on Postgres 17 (PGlite), one
+ * statement per type: `text` and `char` answer rows; `uuid`, `numeric`, `bigint`, `integer`,
+ * `date`, `timestamptz`, `jsonb`, `boolean` and `text[]` all answer
+ * `operator does not exist: <type> ~~ unknown`, and `bytea` answers `Invalid input for bytea type`.
+ *
+ * It has to be the KIND and not the field type, because several kinds render in a text box and
+ * only two of them can be searched: `adminSearch` issues one `contains` filter per searchable
+ * field and the driver compiles `contains` to `<column> like $1` with NO cast
+ * (`packages/entity/src/pg-sql.ts`), so a searchable column of any other kind makes the admin's
+ * search box answer a database error rather than an empty result.
+ */
+const LIKE_ABLE_COLUMN_KINDS: ReadonlySet<string> = new Set(['text', 'char']);
+
+/**
+ * A text box over a column a `LIKE` can run against — both halves required. The type keeps an
+ * enum or a relation out of the search index the way it always has; the kind keeps out the ones
+ * that would throw.
+ */
+export function searchable(type: AdminFieldType, column: AdminColumnFacts): boolean {
+  if (type !== 'text' && type !== 'textarea') return false;
+  return LIKE_ABLE_COLUMN_KINDS.has(column.kind);
 }

package/src/index.ts

@@ -87,6 +87,7 @@ export {
 export {
   ADMIN_ERROR_CODES,
   ADMIN_ERROR_TITLES,
+  AdminActionDuplicateError,
   AdminEntityUnknownError,
   type AdminErrorCode,
   type AdminErrorParts,

package/src/inert-jsx.ts

@@ -0,0 +1,187 @@
+// TEST-ONLY. Calls an admin `.tsx` view as the plain function it is and walks what came back, so
+// a test can assert on the tree a screen produced rather than on a value it also constructed.
+//
+// Which JSX factory a `.tsx` in this package compiled to is NOT ours to choose: `@ultimat3/render`
+// installs a process-global `Bun.plugin` `onLoad` for `/\.tsx$/` at import (`routes.ts` imports it,
+// so any sibling suite can win the race) and `bun test` is one process. Both factories build the
+// same shape — a `type`, a `props`, children under `props.children` — so this walker recognises
+// both and the run's file order stops deciding. Recognising neither is what falls through to
+// `String(value)` and asserts against `"[object Object]"`.
+
+/** `@ultimat3/render`'s node brand, read off the GLOBAL symbol registry rather than imported. */
+const RENDER_NODE: symbol = Symbol.for('ultimate.render.jsx');
+
+export type InertComponent = (props: Record<string, unknown>) => unknown;
+
+export interface InertNode {
+  readonly type: string | InertComponent;
+  readonly props: Record<string, unknown>;
+}
+
+export function isInertNode(value: unknown): value is InertNode {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'inert' in value || RENDER_NODE in value;
+}
+
+/** The classic factory these `.tsx` files fall back to under `jsx: 'preserve'`. */
+export function h(
+  type: string | InertComponent,
+  props: Record<string, unknown> | null,
+  ...children: readonly unknown[]
+): InertNode {
+  const base = { ...(props ?? {}) };
+  if (children.length > 0) base['children'] = children.length === 1 ? children[0] : children;
+  return { inert: true, type, props: base } as unknown as InertNode;
+}
+
+/**
+ * How many installs are live, and what `globalThis.React` was before the first one. A harness that
+ * DELETED the property on the way out destroys a binding it did not create, and a nested install
+ * would tear the factory out from under the suite still using it — the counter is what makes the
+ * last restore the only one that acts.
+ */
+let depth = 0;
+let saved: PropertyDescriptor | undefined;
+
+export function installFactory(): void {
+  if (depth === 0) {
+    // The descriptor, not the value: the property may be a getter or non-writable, and `assign`
+    // onto either throws or silently loses.
+    saved = Object.getOwnPropertyDescriptor(globalThis, 'React');
+    Object.defineProperty(globalThis, 'React', {
+      value: { createElement: h },
+      configurable: true,
+      writable: true,
+      enumerable: true,
+    });
+  }
+  depth += 1;
+}
+
+/** Undo the matching `installFactory()`. Unbalanced calls are inert. */
+export function restoreFactory(): void {
+  if (depth === 0) return;
+  depth -= 1;
+  if (depth > 0) return;
+  if (saved === undefined) Reflect.deleteProperty(globalThis, 'React');
+  else Object.defineProperty(globalThis, 'React', saved);
+  saved = undefined;
+}
+
+/**
+ * Every node in the tree, depth first, with nested components CALLED and thunks invoked — a
+ * component that reads a prop inside one renders nothing until something asks.
+ *
+ * Component nodes are KEPT as well as expanded, so a test can assert on the props a view handed
+ * `<Money>` — the admin's contract with the design system — and not only on the markup ui chose
+ * to emit for them, which is ui's business and changes without this package changing.
+ */
+export function nodesOf(value: unknown): InertNode[] {
+  if (value === null || value === undefined || typeof value === 'boolean') return [];
+  if (typeof value === 'string' || typeof value === 'number') return [];
+  if (Array.isArray(value)) return value.flatMap(nodesOf);
+  if (isInertNode(value)) {
+    if (typeof value.type === 'function') return [value, ...nodesOf(value.type(value.props))];
+    return [value, ...nodesOf(value.props['children'])];
+  }
+  if (typeof value === 'function') return nodesOf((value as () => unknown)());
+  return [];
+}
+
+/**
+ * The tree this package itself built: component nodes are kept but NOT called, so the walk stops
+ * at the design-system boundary. Use this when a design-system component's own internals would
+ * otherwise answer a query about the admin's markup — `<Dialog>` renders a close `<button>`, and a
+ * test asking "which buttons did the action bar render" must not be handed ui's.
+ */
+export function shallowNodesOf(value: unknown): InertNode[] {
+  if (value === null || value === undefined || typeof value === 'boolean') return [];
+  if (typeof value === 'string' || typeof value === 'number') return [];
+  if (Array.isArray(value)) return value.flatMap(shallowNodesOf);
+  if (isInertNode(value)) return [value, ...shallowNodesOf(value.props['children'])];
+  if (typeof value === 'function') return shallowNodesOf((value as () => unknown)());
+  return [];
+}
+
+/** Nodes rendered by the named component — `byComponent(nodes, 'Money')`. */
+export function byComponent(nodes: readonly InertNode[], name: string): InertNode[] {
+  return nodes.filter((node) => typeof node.type === 'function' && node.type.name === name);
+}
+
+const SKIPPED_PROPS = new Set(['children', 'ref', 'innerHTML']);
+
+function attributes(props: Record<string, unknown>): string {
+  return Object.entries(props)
+    .filter(([name, value]) => {
+      if (SKIPPED_PROPS.has(name) || name.startsWith('on')) return false;
+      return value !== undefined && value !== null && value !== false;
+    })
+    .map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${String(value)}"`))
+    .join('');
+}
+
+/** The tree as markup. Unknown values are `String()`d, which the premise test refuses to allow. */
+export function renderHtml(value: unknown): string {
+  if (value === null || value === undefined || typeof value === 'boolean') return '';
+  if (typeof value === 'string' || typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return value.map(renderHtml).join('');
+  if (isInertNode(value)) {
+    if (typeof value.type === 'function') return renderHtml(value.type(value.props));
+    const inner = renderHtml(value.props['children']);
+    return `<${value.type}${attributes(value.props)}>${inner}</${value.type}>`;
+  }
+  if (typeof value === 'function') return renderHtml((value as () => unknown)());
+  return String(value);
+}
+
+/** Render a component to its host nodes. `props` is the component's own, untyped on purpose. */
+export function renderNodes(component: unknown, props: Record<string, unknown> = {}): InertNode[] {
+  return nodesOf((component as InertComponent)(props));
+}
+
+/**
+ * `renderNodes`, stopping at the design-system boundary — the `shallowNodesOf` sibling. The
+ * `unknown` parameter is what makes it usable: a screen's props are typed and generic, so a test
+ * calling one through `as (props: Record<string, unknown>) => unknown` is a conversion TypeScript
+ * refuses outright. One widening here beats one per call site.
+ */
+export function renderShallowNodes(
+  component: unknown,
+  props: Record<string, unknown> = {},
+): InertNode[] {
+  return shallowNodesOf((component as InertComponent)(props));
+}
+
+/** Render a component to markup. */
+export function renderComponent(component: unknown, props: Record<string, unknown> = {}): string {
+  return renderHtml((component as InertComponent)(props));
+}
+
+export function byTag(nodes: readonly InertNode[], tag: string): InertNode[] {
+  return nodes.filter((node) => node.type === tag);
+}
+
+/** Nodes whose attribute equals `value`; `undefined` matches "carries the attribute at all". */
+export function withAttr(nodes: readonly InertNode[], name: string, value?: unknown): InertNode[] {
+  return nodes.filter((node) =>
+    value === undefined ? node.props[name] !== undefined : node.props[name] === value,
+  );
+}
+
+/** The one node a test means, or a throw naming what it looked for — never a silent `undefined`. */
+export function one(nodes: readonly InertNode[], what: string): InertNode {
+  const node = nodes[0];
+  if (node === undefined || nodes.length !== 1) {
+    throw new Error(`expected exactly one ${what}, found ${nodes.length}`);
+  }
+  return node;
+}
+
+/** Call an element's event handler prop, e.g. `fire(button, 'onClick', {})`. */
+export function fire(node: InertNode, handler: string, event: unknown): void {
+  const fn = node.props[handler];
+  if (typeof fn !== 'function') {
+    throw new Error(`node <${String(node.type)}> carries no ${handler}`);
+  }
+  (fn as (e: unknown) => void)(event);
+}

package/src/mcp.ts

@@ -2,7 +2,14 @@
 // `defineAppMcp` so the user's agents drive the user's app. Same authz, same audit, same
 // confirmation rules as the buttons — this file adds a transport, not a second back door.
 
-import { agentActor } from '@ultimat3/core';
+import type { Actor } from '@ultimat3/core';
+import {
+  agentActor,
+  createContext,
+  hasContext,
+  runWithContext,
+  withChildContext,
+} from '@ultimat3/core';
 import {
   type AnyMcpTool,
   type AppMcp,
@@ -257,6 +264,28 @@ function allowedToolNames(
   return names;
 }
 
+/**
+ * Run the call AS the MCP caller — the ambient actor, not only the `CrudCtx` one.
+ *
+ * `AdminApp.ctx()` builds a plain `CrudCtx` and never touches core's async context, so everything
+ * deriving from `tryUseContext()` — entity's tenant guard, the query cache authority, the
+ * jit-preload store — saw whatever actor the TRANSPORT's surrounding request installed rather than
+ * the token's. Over `mcpHttpRoute` mounted in a pipeline that resolves a session cookie, an agent
+ * token authorized as agent X while the repo reads ran as cookie-user Y's tenant; over stdio there
+ * was no context at all, so `actorTenant` was `undefined` and `assertRowTenant` became a no-op and
+ * an admin `create` could name any `orgId`. Same rule as `@ultimat3/mcp`'s `app-tool.ts`: the
+ * caller is the actor for the WHOLE call, by construction rather than by two call sites agreeing.
+ *
+ * Two spellings, one rule, because there are two transports: a child context when a request is
+ * already in flight (it keeps the parent's `requestId` and rebuilds the managed services against
+ * the child's actor), a fresh ROOT context over stdio — where `withChildContext` would throw
+ * `X_NO_CONTEXT` from its own `useContext()`.
+ */
+const asCaller = <T>(actor: Actor, requestId: string, run: () => Promise<T>): Promise<T> =>
+  hasContext()
+    ? withChildContext({ actor }, run)
+    : runWithContext(createContext({ actor, requestId }), run);
+
 function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMcpTool): AnyMcpTool {
   return {
     name: tool.name,
@@ -270,8 +299,11 @@ function toMcpTool(opts: AdminMcpOptions, requestId: () => string, tool: AdminMc
     visibleTo: (caller: McpCaller): boolean =>
       allowedToolNames(opts, requestId, caller).has(tool.name),
     async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
-      const ctx = opts.app.ctx({ actor: adminActorOf(caller), requestId: requestId() });
-      const result = await callAdminTool(opts.app, ctx, tool.name, args);
+      const id = requestId();
+      const ctx = opts.app.ctx({ actor: adminActorOf(caller), requestId: id });
+      const result = await asCaller(caller.actor, id, () =>
+        callAdminTool(opts.app, ctx, tool.name, args),
+      );
       if (result.ok) return jsonResult(result.data);
       // An expected outcome the model should reason about (a policy said no), not a
       // protocol error: the transport still answers 200 with the denial in the body.

package/src/policy-bridge.ts

@@ -15,7 +15,10 @@ export const adminPermissions = definePermissions(ADMIN_PERMISSIONS);
  * mapping lives here because this file is the only one allowed to speak to the policy layer.
  */
 const policyActor = (actor: AdminActor): Actor =>
-  userActor({ id: actor.id, roles: actor.roles ?? [] });
+  // `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 });
 
 /**
  * `evaluate()`'s result is read structurally: the policy layer owns its own decision type,
@@ -55,9 +58,13 @@ export function policyAuthz(input: PolicyAuthzInput): AdminAuthz {
       // `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 }),
+        evaluate(policy, { actor: policyActor(actor), input: payload, ...row }),
       );
     },
   };

package/src/resource.ts

@@ -69,7 +69,16 @@ export interface AdminResourceOptions<Row extends AdminRow = AdminRow> {
 
 export interface AdminResource<Row extends AdminRow = AdminRow> {
   readonly name: string;
-  /** Mount-relative, e.g. `/posts`. */
+  /**
+   * Mount-relative, e.g. `/posts` — the layout composes it with `AdminApp.basePath`, so this is
+   * never the URL on its own.
+   *
+   * Defaults to the entity's `$name` VERBATIM. It used to be `pluralize($name)`, which is why the
+   * reference app's dashboard served `/orgses`, `/postses` and `/commentses`: every entity in both
+   * tracked apps is already named plural (19 of 19), so the heuristic ran a second time on a word
+   * that had already had it. Which plural a name takes is an app's convention and not a mechanism
+   * the framework can own (axiom 8) — `path:` is how an app spells its own.
+   */
   readonly path: string;
   readonly titleKey: string;
   readonly group: string;
@@ -90,12 +99,6 @@ export interface AdminResource<Row extends AdminRow = AdminRow> {
   field(name: string): AdminField;
 }
 
-const pluralize = (name: string): string => {
-  if (/[sxz]$/.test(name) || /(ch|sh)$/.test(name)) return `${name}es`;
-  if (/[^aeiou]y$/.test(name)) return `${name.slice(0, -1)}ies`;
-  return `${name}s`;
-};
-
 function deriveField(
   entity: AdminEntity,
   column: AdminColumnFacts,
@@ -131,7 +134,7 @@ function deriveField(
     sortable: override?.sortable ?? sortable(type, column),
     // Generated columns are excluded from search: an id is found by exact lookup, and a
     // `contains` over a uuid column is a scan that returns nothing useful.
-    searchable: override?.searchable ?? (searchable(type) && !sensitive && !generated),
+    searchable: override?.searchable ?? (searchable(type, column) && !sensitive && !generated),
     ...(values === undefined ? {} : { values }),
     ...(currency === undefined ? {} : { currency }),
     ...(relation === undefined ? {} : { relation }),
@@ -213,7 +216,9 @@ function pickListFields(
           entity: entityName,
           field: name,
           cause: 'listed in listFields but not a column of the entity',
-          fix: `remove "${name}" from listFields, or add the column with x g migration`,
+          // `x db gen` and NOT `x g migration`: there is no `migration` generator, and the fix
+          // line an operator pastes has to be a command the CLI actually dispatches.
+          fix: `remove "${name}" from listFields, or add the column with x db gen "add ${name} to ${entityName}"`,
         });
       }
       return field;
@@ -261,7 +266,7 @@ export function adminResource<Row extends AdminRow = AdminRow>(
 
   const resource: AdminResource<Row> = {
     name: entity.$name,
-    path: opts.path ?? `/${pluralize(entity.$name)}`,
+    path: opts.path ?? `/${entity.$name}`,
     titleKey: opts.titleKey ?? `admin.${entity.$name}.title`,
     group: opts.group ?? 'admin.group.data',
     idField,