@ultimat3/admin 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -7,8 +7,13 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 ## Rules
 
 - **One authz.** `AdminAuthz` (`authz.ts`) is the only decision path. `action-gate.ts`, `crud.ts` and `page-guard.tsx` call `decideAll`; views render what the gate returned. Never add a second check in a view or an MCP handler.
+- **The subject carries the tenant and the loaded row.** `AdminActor.orgId` reaches `policyActor` and `AdminSubject.row` reaches `evaluate`, so an org-scoped or ownership rule can fire at all. It could not: every admin decision was evaluated with `actor.orgId === undefined` and `row === null`, so a role-only rule allowed and the coarse `admin:read` + `<entity>:read` pair was the only gate on a row — while `adminList`/`adminSearch` add no tenant predicate of their own. `adminDetail`, `adminUpdate` and `adminDestroy` load the row BEFORE the guard, the shape `packages/action/src/invoke.ts` uses; `undefined` means "not loaded" and is left off the subject, `null` means "looked and found none" and fails a row rule closed. Pinned in `policy-subject.test.ts`, which asserts the SUBJECT a policy receives — `staticAuthz` is a grant-list stub and no suite driving it can see any of this.
+- **The MCP caller is the ambient actor for the whole call.** `mcp.ts` wraps `callAdminTool` in a child context (or a fresh root one over stdio, where there is no surrounding request), the same rule `@ultimat3/mcp`'s `app-tool.ts` states. `AdminApp.ctx()` builds a plain `CrudCtx` and touches nothing async-local, so everything deriving from `tryUseContext()` — entity's tenant guard, the query cache authority, the jit-preload store — read the TRANSPORT's actor: an agent token authorized as agent X while the repo reads ran as the cookie user's tenant, and over stdio `actorTenant` was `undefined` and `assertRowTenant` a no-op. Pinned in `mcp-context.test.ts`.
 - **A custom page's guard is composed, never written.** `pages.ts` turns a `pages:` entry into an `AdminRoute` carrying `[admin:read, …declared]`; `routes.ts` is the only thing that may hand a page component to a router and it hands the `guardedPage()` wrapper, with `permissions[0]` already in `defineRoute({ policy })`. `AdminPageProps.ctx` is required by the type so the wrapper cannot be bypassed by calling the component directly. An empty permission list is `X_ADMIN_PAGE_UNGUARDED` at `defineAdmin` time — the one place an unauthenticated admin screen could have been born.
+- **One `AdminAction.name`, one handler.** The name is the MCP tool name (`admin.action.<name>`), the default label key, AND the key `callAdminTool` resolves a handler by — three addresses, one string. Two actions sharing it is `X_ADMIN_ACTION_DUPLICATE` at `defineAdmin` time (`admin.ts`, `mcp.test.ts`), not at the first agent call: `.find()` on a name dispatches to whichever resource came first, which is a call that SUCCEEDS against the wrong action and reports nothing. Refused at declaration rather than in `adminMcp()` because an app that renders the dashboard and never wires MCP has the same two broken label keys and the same ambiguous dispatch. The framework's own examples already qualify the name with the entity (`post.publish`) — the `fix:` line is that convention, made into the instruction. The same object attached through both `actions:` and `resources[e].actions` is one action, not two: identity, not name, is what "already seen" means.
 - **A host that serves an admin URL itself reads its gate, never restates it.** `adminRouteFor(app, path)` (`routes.ts`) is that read, and `AdminRouteConfig.policy` is what it hands over — the same object `config.policy` carries, non-optional so a caller need not prove it exists. Typing `policy: { permission: 'admin:read' }` into a page file beside a route table that already declares one for that URL is two declarations of one URL's authz; they agree until somebody edits one. The deployed demo shipped exactly that on five pages until 1.2.0, and its `apps/admin/app/admin/route-policy.test.ts` is the rule made executable: a quoted permission anywhere under `app/admin/**/page.tsx` fails the suite. An undeclared path is `X_ADMIN_PAGE_PATH_INVALID`, listing the paths that would have worked.
+- **A `/_x` source reads a registry through its DESCRIPTOR TYPE, never as an untyped bag.** `import type { RouteDescriptor }` beside the dynamic `import()` — the type is erased, so /_x still costs the production graph nothing, and a renamed descriptor field becomes a typecheck failure in `dev/data.ts` naming the field. The bag was defended here as tolerance and bought three panels that were wrong for every row and could not go red: `route['render']`, `route['budget']`, `route['revalidate']`, `job['idempotencyKey']` and `entity['drift']` are names no descriptor has ever published, so a read answered `undefined`, took the fallback, and shipped the fallback as a fact — every route `stream` with no budget and no tag, every job non-idempotent, every schema drift-free. `dev/published-keys.test.ts` is the runtime half a type cannot answer: it walks what the real registries EMIT, so a field the type declares and the projection never writes is a red test.
+- **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `hasMeta` was dropped because `defineRoute()` refuses a route with no `meta`, so `missingMeta` was a defect list with no member it could hold; `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key — a guarantee shown where the question is asked. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
 - **One bridge per foreign package.** `policy-bridge.ts` is the only file calling `evaluate`/`definePermissions`; `routes.ts` the only one calling `defineRoute`; `mcp.ts` the only one calling `defineAppMcp`; `dev/data.ts` the only one importing introspection (dynamically — `/_x` must stay out of the production graph). Source only: a **test** declares the permissions its own `can()` fixtures use, because `definePermissions` writes a process-global registry and `bun test` seats several files in one process — `dev/data.test.ts` relied on the empty-registry-means-permissive fallback and went red the first time it shared a process with anything that imports this package.
 - **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.
@@ -24,7 +29,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider: a bare `catch` in `dev/panel-live.ts` reported an authz refusal and a dropped NATS connection from a *running* sync node as `dev.live.no-sync-node`, telling the reader to install a tier they already had. 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 — it used to build `/${entity}s/${id}`, which is English pluralisation by concatenation and drops `basePath`. The route table is `AdminApp`'s; a widget three layers down does not get to guess it.
 - **One read-only SQL guard, and it is `@ultimat3/mcp`'s — the whole verdict, with nothing held back.** `dev/panel-db.ts` calls `assertReadOnlyQuery` (tier 5 → tier 4, already a dependency) rather than keeping a second keyword scan: that guard also refuses a batch, a call into the `pg_read_*`/`pg_advisory_*`/`pg_sleep`/`set_config` families, `FOR UPDATE`, and a delimiter that never closes in all five forms (`'`, `E'`, `"`, `$tag$`, slash-star). A local unterminated-delimiter refusal lived here for one revision and was **deleted**: it tested for a surviving `'`/`"`, so it covered three of the five and called a dollar-quoted body "a quote" — one failure mode, two explanations, and a second detector for a property the guard below already tests. What stays local is the emptiness test and the **way out**: `@ultimat3/mcp` tells its caller to expose an action, which a developer at `/_x` cannot act on. The panel says "Fix the statement, or — if it is meant to write — run it with `x db psql --write`", conditional on purpose: `--write` grants writes, it does not close a delimiter, and it used to be printed as *the* fix for a syntax error.
-- **Every admin operation is audited, reads included.** `adminList` was the one call that logged nothing in either direction; `ListResult` now carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`), because the subject of a listing is not a row.
+- **Every admin operation is audited, reads included.** `adminList` was the one call that logged nothing in either direction; `ListResult` now carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`), because the subject of a listing is not a row. `adminSearch` was the second, and it read rows out of EVERY readable entity: `AdminSearchResult.audit` now carries one entry per resource it decided about — `allowed` per searched resource, a `deniedDraft` per refused one. A resource skipped for having no text field or no repo is not an authz event and writes none.
 - Money through `assertMoney`, timestamps through `assertZone`, pagination through `pagination.ts`. No `offset`, ever.
 - **One cursor codec.** `pagination.ts` is the only file calling core's `encodeCursor`/`decodeCursor`; it wraps them as `encodeAdminCursor`/`decodeAdminCursor`, scoped `admin:<resource>`. An invalid cursor is page one here, not an error page — but the signature is checked first, so a forged one cannot seek.
 - Labels are i18n keys derived in `resource.ts` (`admin.<entity>.field.<name>`); only `.tsx` calls `t()`. MCP tool descriptions are literal English (protocol payload, not UI copy).

package/README.md

@@ -17,11 +17,11 @@ One panel per file. Each kills one question, and each is available as `--json`
 
 | Panel | Kills |
 |---|---|
-| `routes` | which handler serves this? — render mode, offline strategy, budget, meta |
+| `routes` | which handler serves this? — render mode, offline strategy, revalidate tags, budget |
 | `timeline` | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count |
 | `live` | what does each subscriber receive, and **why** — the matcher's decision trace |
 | `jobs` | queue depth, step traces, retry-from-step target, dead letter |
-| `db` | psql in a tab (read-only; `assertReadOnly` refuses DML), schema diff vs migrations |
+| `db` | psql in a tab (read-only; `assertReadOnly` refuses DML), schema + drift (`null` unless a host wires the check) |
 | `mail` | caught mail, rendered, per locale, with the locale gaps listed |
 | `cache` | the tag graph — what invalidated what, and which tags are orphans |
 | `policy` | the permission matrix per actor, every cell carrying its trace |
@@ -201,7 +201,10 @@ shape already is, written down once so two apps do not invent two layouts. `x g
 | Every mutation and every denial is on the audit log, with a before/after diff | `audit.ts` |
 | Branding aliases tokens only — `accent: '#7c3aed'` is a compile error | `theme.ts` |
 
-Single-row reads are audited; list pages are not (volume).
+Reads are audited too, and on both branches: `adminDetail` keys its entry on the row,
+`adminList` and `adminSearch` key theirs on the table (`entityId: null`), and a refusal is an
+entry of its own. `AdminSearchResult.audit` carries one entry per resource the call decided
+about — searched or refused — so a jump box that walked every readable entity leaves a trace.
 
 ## AI-first
 

package/package.json

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

package/src/admin.ts

@@ -6,6 +6,7 @@ import { type AuditLog, memoryAuditLog } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
 import type { CrudCtx } from './crud';
 import { permissionsForOperation } from './crud';
+import { AdminActionDuplicateError } from './errors';
 import { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
 import { type AdminCustomPage, type AdminPageComponent, pageNavItems, pageRoutes } from './pages';
 import type { AdminOperation } from './permissions';
@@ -124,6 +125,37 @@ function resourceRoutes(basePath: string, resource: AdminResource): readonly Adm
   return routes;
 }
 
+/**
+ * One `AdminAction.name`, one handler. The name is the MCP tool name (`admin.action.<name>`), the
+ * default label key (`admin.action.<name>`) AND the key `callAdminTool` resolves a handler by, so
+ * two actions sharing it dispatch to whichever `.find()` reached first — a call that succeeds
+ * against the wrong action and reports nothing. Refused here rather than in `adminMcp()`, because
+ * an app that renders the dashboard and never wires MCP has the same two broken label keys and
+ * the same ambiguous dispatch.
+ *
+ * Identity, not name, is what "already seen" means: `defineAdmin` attaches `input.actions` to the
+ * entity each one names AND appends `resources[<entity>].actions`, so an author who spelled the
+ * same object in both meant one action, not two.
+ */
+function assertUniqueActionNames(
+  resources: readonly AdminResource[],
+  declared: readonly AdminAction[],
+): void {
+  const seen = new Map<string, { readonly action: AdminAction; readonly entities: string[] }>();
+  // `declared` is every action the caller passed, not just the global ones: an action naming an
+  // entity that is not in `entities` reaches neither list, and its name still has to be unique.
+  for (const action of [...resources.flatMap((resource) => resource.actions), ...declared]) {
+    const found = seen.get(action.name);
+    if (found === undefined) {
+      seen.set(action.name, { action, entities: [action.entity ?? 'the global toolbar'] });
+      continue;
+    }
+    if (found.action === action) continue;
+    found.entities.push(action.entity ?? 'the global toolbar');
+    throw new AdminActionDuplicateError({ name: action.name, entities: found.entities });
+  }
+}
+
 /** Derive the whole admin from the registries. */
 export function defineAdmin(input: DefineAdminInput): AdminApp {
   const basePath = input.basePath ?? '/admin';
@@ -141,6 +173,8 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     });
   });
 
+  assertUniqueActionNames(resources, actions);
+
   const pages = input.pages ?? [];
   const navOptions = input.nav ?? {};
   const extra: readonly (NavItem & { readonly group: string })[] = [

package/src/authz.ts

@@ -11,6 +11,14 @@ import { ADMIN_PERMISSION_SPEC, type AdminPermission } from './permissions';
 
 export interface AdminActor {
   readonly id: string;
+  /**
+   * The tenant this operator acts under. NOT optional in practice on a multi-tenant app: the
+   * admin's subject reached `policyAuthz` with `orgId: undefined`, so an org-scoped rule could
+   * not fire and a role-only rule allowed — while `adminList`/`adminSearch` add no tenant
+   * predicate of their own. Absent still means "single-tenant app", which is why the type keeps
+   * it optional; a rule that reads it must fail closed on `undefined` like any other policy.
+   */
+  readonly orgId?: string;
   readonly roles?: readonly string[];
   /** BCP-47. Drives every `t()` call and every `Intl` format in the admin. */
   readonly locale?: string;
@@ -23,6 +31,16 @@ export interface AdminSubject {
   readonly entity?: string;
   readonly id?: string;
   readonly input?: unknown;
+  /**
+   * The already-loaded row, for a row-level rule. `null` means "no row was loaded", which the
+   * policy layer treats as no evidence of permission — same contract as an `action`'s `row:`
+   * loader. Absent entirely means the surface has no row to load (a list page, a create form).
+   *
+   * Without it every admin decision evaluated with `row: null` and `input = { entity, id }`, so
+   * an ownership rule could not fire at all and the coarse `admin:read` + `<entity>:read` pair
+   * was the only gate on a single row.
+   */
+  readonly row?: unknown;
 }
 
 export interface AdminDecision {

package/src/crud.ts

@@ -59,10 +59,20 @@ export function decideOperation(
   op: AdminOperation,
   ctx: CrudCtx,
   id?: string,
+  /**
+   * The row the surface ALREADY loaded, or `null` for "looked and found none". `undefined` means
+   * not loaded at all — a list page, a create form, a nav button — and is left off the subject
+   * entirely, because "there is no row here" and "there is a row and nobody loaded it" are
+   * different facts and only the second is a bug. Every admin decision used to be evaluated
+   * without one, so an ownership rule could not fire and the coarse `admin:read` + `<entity>:read`
+   * pair was the only gate on a single row.
+   */
+  row?: AdminRow | null,
 ): AdminDecision {
   return decideAll(ctx.authz, permissionsForOperation(resource.name, op), ctx.actor, {
     entity: resource.name,
     ...(id === undefined ? {} : { id }),
+    ...(row === undefined ? {} : { row }),
   });
 }
 
@@ -140,9 +150,12 @@ export async function adminDetail<Row extends AdminRow>(
   ctx: CrudCtx,
   id: string,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'detail', ctx, id);
-  if (!decision.allowed) return refuse(resource, 'detail', ctx, decision, id);
+  // The row is loaded BEFORE the guard, the shape `packages/action/src/invoke.ts` uses for a
+  // row-level `policy`: a rule that decides about a row cannot decide without one, and the
+  // predicate has to stay synchronous. A denial still returns no row.
   const row = await repoOf(resource).find(id);
+  const decision = decideOperation(resource, 'detail', ctx, id, row);
+  if (!decision.allowed) return refuse(resource, 'detail', ctx, decision, id);
   return {
     ok: true,
     row,
@@ -196,11 +209,13 @@ export async function adminUpdate<Row extends AdminRow>(
   id: string,
   patch: Readonly<Record<string, unknown>>,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'update', ctx, id);
-  if (!decision.allowed) return refuse(resource, 'update', ctx, decision, id);
-
+  // `before` was already loaded here, just after the guard rather than before it — so the rule
+  // that decides whether this actor may touch THIS row never saw the row.
   const repo = repoOf(resource);
   const before = await repo.find(id);
+  const decision = decideOperation(resource, 'update', ctx, id, before);
+  if (!decision.allowed) return refuse(resource, 'update', ctx, decision, id);
+
   const parsed = await validateInput(resource.entity.$schema, { ...(before ?? {}), ...patch });
   if (!parsed.ok) return invalid(resource, 'update', ctx, id, parsed.issues, decision);
 
@@ -208,9 +223,16 @@ export async function adminUpdate<Row extends AdminRow>(
   // strip (undeclared, or normalized to a different value) must never reach the repo. Scoped
   // to the keys actually submitted, so a partial update stays partial rather than rewriting
   // every field of `before` too.
+  // `Object.hasOwn`, not `key in`: `in` walks the prototype chain, so a patch naming `toString`,
+  // `constructor` or `__proto__` put an inherited member into the object handed to `repo.update`
+  // — the exact thing the paragraph above says cannot happen. Over MCP the transport refuses
+  // those keys (`additionalProperties: false`), but `callAdminTool` and `adminUpdate` are both
+  // public API and `mcp.ts` keeps its own gate for a direct call and a future transport.
   const submittedKeys = Object.keys(patch);
   const validatedPatch: Readonly<Record<string, unknown>> = Object.fromEntries(
-    submittedKeys.filter((key) => key in parsed.value).map((key) => [key, parsed.value[key]]),
+    submittedKeys
+      .filter((key) => Object.hasOwn(parsed.value, key))
+      .map((key) => [key, parsed.value[key]]),
   );
   const after = await repo.update(id, validatedPatch);
   return {
@@ -238,7 +260,9 @@ export async function adminDestroy<Row extends AdminRow>(
   id: string,
   confirmation: string | undefined,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'delete', ctx, id);
+  const repo = repoOf(resource);
+  const before = await repo.find(id);
+  const decision = decideOperation(resource, 'delete', ctx, id, before);
   if (!decision.allowed) return refuse(resource, 'delete', ctx, decision, id);
 
   const expected = confirmationToken(resource.name, id);
@@ -258,8 +282,6 @@ export async function adminDestroy<Row extends AdminRow>(
     );
   }
 
-  const repo = repoOf(resource);
-  const before = await repo.find(id);
   await repo.destroy(id);
   return {
     ok: true,

package/src/detail.tsx

@@ -33,6 +33,18 @@ export interface AdminDetailProps<Row extends AdminRow> {
   readonly onCancel?: () => void;
 }
 
+/**
+ * The audit row's verb. `operation` holds a CRUD verb for `kind: 'operation'` and the ACTION NAME
+ * for `kind: 'action'`, and the catalog declares only `admin.operation.{list,detail,search,create,
+ * update,delete,page}` — so an entry for `post.publish` rendered the literal key
+ * `admin.operation.post.publish` into the page. `admin.action.<name>` is the same key
+ * `action-gate.ts` gives the button that ran it, so the two read identically.
+ */
+export const operationLabel = (entry: AuditEntry): string =>
+  entry.kind === 'action'
+    ? t(`admin.action.${entry.operation}`)
+    : t(`admin.operation.${entry.operation}`);
+
 export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>): JSX.Element {
   if (props.error !== null) {
     return <ErrorState error={adminErrorFrom(props.error)} />;
@@ -102,7 +114,7 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
             {props.audit.map((entry) => (
               <li>
                 <code>{entry.at}</code> <span>{entry.actor.id}</span>{' '}
-                <span>{t(`admin.operation.${entry.operation}`)}</span>{' '}
+                <span>{operationLabel(entry)}</span>{' '}
                 <span data-outcome={entry.outcome}>
                   {t(`admin.audit.outcome.${entry.outcome}`)}
                 </span>

package/src/dev/data.ts

@@ -63,17 +63,6 @@ export function staticDevSources(facts: Partial<DevSources> = {}): DevSources {
   };
 }
 
-type Bag = Readonly<Record<string, unknown>>;
-
-const bagOf = (value: unknown): Bag =>
-  typeof value === 'object' && value !== null ? (value as Bag) : {};
-const str = (value: unknown, fallback = ''): string =>
-  typeof value === 'string' ? value : fallback;
-const numOf = (value: unknown, fallback = 0): number =>
-  typeof value === 'number' ? value : fallback;
-const listOf = (value: unknown): readonly unknown[] => (Array.isArray(value) ? value : []);
-const strings = (value: unknown): readonly string[] => listOf(value).map((item) => String(item));
-
 export interface DevSourceOptions {
   /** The app's authz. The policy matrix is computed through it, never re-derived. */
   readonly authz?: AdminAuthz;
@@ -136,9 +125,19 @@ const STEP_STATUS: Readonly<Record<StepStatus, JobStepFact['status']>> = {
 };
 
 /**
- * Registry output is read field by field: a registry that grows a field must not break the
- * dev dashboard, and a registry that renames one should show a blank cell in /_x rather than
- * crash the process an engineer is debugging with.
+ * Every registry is read through its OWN descriptor type, not as an untyped bag. The bag was
+ * defended here as tolerance — "a renamed field should show a blank cell rather than crash the
+ * process an engineer is debugging with" — and what it actually bought was three panels that
+ * were wrong for every row and could not go red: `route['render']`, `route['budget']`,
+ * `route['revalidate']` and `job['idempotencyKey']` are names no descriptor has ever published,
+ * so /_x reported every route as `stream` with no budget and every job as non-idempotent.
+ *
+ * The packages ship in lockstep at one version, so a renamed descriptor field is a rename this
+ * file can be edited with — as a TYPECHECK failure naming the field, which is the tolerance
+ * worth having. It costs the production graph nothing: `await import('@ultimat3/render')` is
+ * typed by the module it resolves to, so /_x is still reached only through the dynamic import
+ * and no descriptor type has to be named here at all. `published-keys.test.ts` is the other
+ * half — it walks what the real registries EMIT, which a stale `dist/*.d.ts` would hide.
  */
 export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
   const hooks = opts.hooks ?? {};
@@ -146,23 +145,26 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
   const sources: DevSources = {
     async routes(): Promise<readonly RouteFact[]> {
       const { describeRoutes } = await import('@ultimat3/render');
-      return listOf(describeRoutes()).map((raw) => {
-        const route = bagOf(raw);
-        const budget = bagOf(route['budget']);
-        return {
-          path: str(route['path']),
-          render: str(route['render'], 'stream'),
-          offline: str(route['offline'], 'network-only'),
-          hydrate: str(route['hydrate'], 'idle'),
-          handler: str(route['handler'], str(route['file'])),
-          budget: {
-            ...(typeof budget['js'] === 'string' ? { js: budget['js'] } : {}),
-            ...(typeof budget['lcp'] === 'number' ? { lcp: budget['lcp'] } : {}),
-          },
-          revalidateTags: strings(bagOf(route['revalidate'])['tags']),
-          hasMeta: route['meta'] !== undefined,
-        };
-      });
+      return describeRoutes().map((route) => ({
+        path: route.path,
+        // `RouteDescriptor` calls the render mode `mode`; the panel's own word is `render`, and
+        // the two are bridged here, once. Reading `route['render']` answered `undefined` for
+        // every route, so the fallback shipped — `stream` for the whole table, forever.
+        render: route.mode,
+        offline: route.offline,
+        hydrate: route.hydrate,
+        // A descriptor has no `handler`: the FILE is what names the row.
+        handler: route.file,
+        // Two flat fields on the descriptor, one nested bag on the fact — the panel's budget
+        // check reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
+        budget: {
+          ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
+          ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
+        },
+        // `revalidateTags`, already flattened to keys — never `revalidate.tags`, a shape the
+        // descriptor does not have and which answered `[]` for every ISR route in the app.
+        revalidateTags: route.revalidateTags,
+      }));
     },
 
     traces: unwired<readonly RequestTrace[]>('traces', 'timeline'),
@@ -186,38 +188,30 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
           entry.sql,
         ]),
       );
-      return listOf(queries).map((raw) => {
-        const query = bagOf(raw);
-        const name = str(query['name']);
-        return {
-          name,
-          live: query['live'] === true,
-          // `QueryDescriptor`'s permission field is named `capability`, not `policy` — this
-          // fact keeps its own field named `policy` (that is the /_x rendering, not the registry).
-          policy: str(query['capability']),
-          sql: sqlByName.get(name) ?? null,
-        };
-      });
+      return queries.map((query) => ({
+        name: query.name,
+        live: query.live,
+        // `QueryDescriptor`'s permission field is named `capability`, not `policy` — this
+        // fact keeps its own field named `policy` (that is the /_x rendering, not the registry).
+        policy: query.capability,
+        sql: sqlByName.get(query.name) ?? null,
+      }));
     },
 
     subscribers: unwired<readonly LiveSubscriberFact[]>('subscribers', 'live'),
 
     async jobDefs(): Promise<readonly JobDefFact[]> {
       const { describeJobs } = await import('@ultimat3/jobs');
-      return listOf(describeJobs()).map((raw) => {
-        const job = bagOf(raw);
-        const retry = bagOf(job['retry']);
-        return {
-          name: str(job['name']),
-          queue: str(job['queue'], 'default'),
-          steps: strings(job['steps']),
-          retry: {
-            attempts: numOf(retry['attempts'], 1),
-            backoff: str(retry['backoff'], 'exponential'),
-          },
-          idempotent: job['idempotencyKey'] !== undefined,
-        };
-      });
+      return describeJobs().map((job) => ({
+        name: job.name,
+        queue: job.queue,
+        steps: job.steps,
+        retry: { attempts: job.retry.attempts, backoff: job.retry.backoff },
+        // The descriptor's own boolean. `job['idempotencyKey']` was a read of the DEFINITION's
+        // field on a descriptor that never carried it, so every job on the panel reported
+        // non-idempotent — the opposite of what `job()` refuses to register without.
+        idempotent: job.idempotent,
+      }));
     },
 
     async queues(): Promise<readonly QueueFact[]> {
@@ -301,38 +295,28 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
 
     async tables(): Promise<readonly TableFact[]> {
       const { describeEntities } = await import('@ultimat3/entity');
-      return listOf(describeEntities()).map((raw) => {
-        const entity = bagOf(raw);
-        return {
-          name: str(entity['table'], str(entity['name'])),
-          // `EntityDescription.columns` is a LIST of physical columns — money is already two
-          // of them here. Reading it as a record produced a table whose columns were "0", "1".
-          columns: listOf(entity['columns']).map((rawColumn) => {
-            const column = bagOf(rawColumn);
-            return {
-              name: str(column['column'], str(column['property'], 'unknown')),
-              type: str(column['kind'], 'unknown'),
-              nullable: column['notNull'] !== true,
-            };
-          }),
-        };
-      });
+      return describeEntities().map((entity) => ({
+        name: entity.table,
+        // `EntityDescription.columns` is a LIST of physical columns — money is already two
+        // of them here. Reading it as a record produced a table whose columns were "0", "1".
+        columns: entity.columns.map((column) => ({
+          // The PHYSICAL name, which is the vocabulary a psql tab speaks.
+          name: column.column,
+          type: column.kind,
+          nullable: !column.notNull,
+        })),
+      }));
     },
 
-    async drift(): Promise<readonly DriftFact[]> {
-      const { describeEntities } = await import('@ultimat3/entity');
-      return listOf(describeEntities()).flatMap((raw) => {
-        const entity = bagOf(raw);
-        return listOf(entity['drift']).map((rawIssue) => {
-          const issue = bagOf(rawIssue);
-          return {
-            table: str(entity['table'], str(entity['name'])),
-            column: typeof issue['column'] === 'string' ? issue['column'] : null,
-            issue: str(issue['issue'], 'unknown'),
-          };
-        });
-      });
-    },
+    /**
+     * Unwired, and it has to be: drift is a COMPARISON — the entities this process declares
+     * against the columns a database actually has — and `describeEntities()` is only one half of
+     * it. This source used to read a `drift` key off `EntityDescription`, which has never had one,
+     * so the panel answered `[]` for every app and every schema: "no drift" printed over a
+     * database nobody looked at. Only a host holding the connection can answer (`x db migrate`'s
+     * `checkDrift`), so it wires the hook or the panel says the check did not run.
+     */
+    drift: unwired<readonly DriftFact[]>('drift', 'db'),
 
     runSql: unwired<SqlResult>('runSql', 'db'),
     mail: unwired<readonly MailFact[]>('mail', 'mail'),
@@ -347,16 +331,13 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         import('@ultimat3/cache'),
         import('@ultimat3/entity'),
       ]);
-      return listOf(describeEntities()).map((raw) => {
-        const name = str(bagOf(raw)['name']);
-        return {
-          tag: name,
-          dependents: listOf(dependentsOf([{ entity: name }])).map((rawDep) => {
-            const dep = bagOf(rawDep);
-            return { kind: str(dep['kind']), id: str(dep['id']) };
-          }),
-        };
-      });
+      return describeEntities().map((entity) => ({
+        tag: entity.name,
+        dependents: dependentsOf([{ entity: entity.name }]).map((dependent) => ({
+          kind: dependent.kind,
+          id: dependent.id,
+        })),
+      }));
     },
 
     invalidations: unwired<readonly InvalidationFact[]>('invalidations', 'cache'),
@@ -379,11 +360,15 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         });
       }
       const { describeActions } = await import('@ultimat3/action');
-      // `ActionDescriptor`'s permission field is named `capability`, not `policy` — reading the
-      // latter answered '' for every action, so the matrix came back empty even when both
-      // `authz` and `actors` were wired correctly.
+      // `permissions`, NOT `capability`. `capability` is the policy's DISPLAY label and
+      // `action.ts` says so: a composite renders as `and(post:read, org:member)`, which is not a
+      // permission and can never be granted — so every composite-guarded action was a
+      // permanently-denied row, and an operator read a real grant as missing. `permissions` is
+      // the flattened list a grant is actually matched against. This is the SECOND time the two
+      // were confused: `x policy list` reported the same actions as unenforced for the same
+      // reason, and `ActionDescriptor.permissions` carries that history in its own doc comment.
       const permissions = [
-        ...new Set(listOf(describeActions()).map((raw) => str(bagOf(raw)['capability']))),
+        ...new Set(describeActions().flatMap((action) => action.permissions)),
       ].filter((permission) => permission !== '');
 
       return actors.flatMap((actor) =>

package/src/dev/facts.ts

@@ -1,15 +1,27 @@
 // The facts a /_x panel may read: one shape per introspection call. Kept apart from the
 // sources that produce them so a panel imports the shape it renders and nothing else.
 
+/**
+ * One row of the route table, in the panel's own words: `render` is the descriptor's `mode` and
+ * `handler` is its `file`. Both renames are made in `data.ts`, once.
+ *
+ * There is no `hasMeta`, deliberately. `defineRoute()` REFUSES a route with no `meta` function
+ * (`packages/render/src/route.ts`), so every registered route has one and the field could only
+ * ever be `true` — it was published as `false` for every route instead, off a `meta` key no
+ * descriptor carries, and fed a `missingMeta` list that can never have a member. Whether the meta
+ * a route returns is any GOOD is a render-time question: `meta` takes the loaded data, so nothing
+ * static can answer it, and a list that always reads "0 routes missing meta" is worse than absent.
+ */
 export interface RouteFact {
   readonly path: string;
+  /** `RouteDescriptor.mode` — `ssr`, `isr`, `static`, `stream`, `spa`. */
   readonly render: string;
   readonly offline: string;
   readonly hydrate: string;
+  /** The route's source file: what names the row. A descriptor publishes no handler. */
   readonly handler: string;
   readonly budget: { readonly js?: string; readonly lcp?: number };
   readonly revalidateTags: readonly string[];
-  readonly hasMeta: boolean;
 }
 
 /**
@@ -85,6 +97,12 @@ export interface JobDefFact {
   readonly queue: string;
   readonly steps: readonly string[];
   readonly retry: { readonly attempts: number; readonly backoff: string };
+  /**
+   * `JobDescriptor.idempotent` — `true` for every registered job, because `job()` refuses a
+   * definition with no `idempotencyKey`. Published rather than assumed: it read the DEFINITION's
+   * `idempotencyKey` off a descriptor that never carried it, so the panel called every job in
+   * the app unsafe to retry.
+   */
   readonly idempotent: boolean;
 }
 
@@ -153,6 +171,11 @@ export interface TableFact {
   readonly columns: readonly ColumnFact[];
 }
 
+/**
+ * One column the database and the entities disagree about. A COMPARISON, so no registry can
+ * produce it alone — `DevSources.drift` is a hook a host holding the connection wires, and the
+ * db panel reports `drift: null` ("nobody checked") rather than `[]` ("nothing wrong") without it.
+ */
 export interface DriftFact {
   readonly table: string;
   readonly column: string | null;

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/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,
@@ -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,

package/src/search.ts

@@ -3,8 +3,10 @@
 // the same `admin:read` + `<entity>:read` pair gates the hit and the detail page it links to.
 
 import { expectedQueryLoop } from '@ultimat3/db';
+import { type AuditEntry, deniedDraft } from './audit';
+import { denied } from './authz';
 import type { CrudCtx } from './crud';
-import { canOperate } from './crud';
+import { decideOperation } from './crud';
 import type { AdminFilter, AdminRow } from './registry';
 import { rowId } from './registry';
 import { type AdminResource, repoOf } from './resource';
@@ -29,6 +31,14 @@ export interface AdminSearchResult {
   readonly searched: readonly string[];
   /** Resources left out, and why — so an operator is never silently shown a subset. */
   readonly skipped: readonly { readonly entity: string; readonly reason: string }[];
+  /**
+   * One entry per resource this call decided about: allowed, or refused. Search read rows out of
+   * every readable entity and wrote NOTHING, on either path — while `permissions.ts` carries
+   * `audited: true` for it, `audit.ts` says denied attempts are logged too, and `CLAUDE.md` says
+   * "every admin operation is audited, reads included". Shaped like `adminList`'s: the subject is
+   * the table, so there is no `entityId`.
+   */
+  readonly audit: readonly AuditEntry[];
 }
 
 export interface AdminSearchInput {
@@ -89,20 +99,45 @@ function labelOf(row: AdminRow, resource: AdminResource): string {
   return rowId(row, resource.idField);
 }
 
+const SKIPPED_FORBIDDEN = 'admin.search.skipped.forbidden';
+
 export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchResult> {
+  const { ctx } = input;
   const term = input.term.trim();
   const limit = input.limitPerResource ?? DEFAULT_LIMIT_PER_RESOURCE;
   const searched: string[] = [];
   const skipped: { entity: string; reason: string }[] = [];
   const hits: AdminSearchHit[] = [];
+  const audit: AuditEntry[] = [];
 
-  if (term === '') return { term, hits: [], searched: [], skipped: [] };
+  // Nothing was decided and nothing was read, so there is nothing to log: an empty term never
+  // reaches a repo.
+  if (term === '') return { term, hits: [], searched: [], skipped: [], audit: [] };
 
   for (const resource of input.resources) {
-    if (!canOperate(resource, 'search', input.ctx)) {
-      skipped.push({ entity: resource.name, reason: 'admin.search.skipped.forbidden' });
+    const offered = resource.operations.includes('search');
+    const decision = decideOperation(resource, 'search', ctx);
+    if (!offered || !decision.allowed) {
+      skipped.push({ entity: resource.name, reason: SKIPPED_FORBIDDEN });
+      audit.push(
+        await ctx.audit.append(
+          deniedDraft({
+            requestId: ctx.requestId,
+            actor: ctx.actor,
+            operation: 'search',
+            kind: 'operation',
+            entity: resource.name,
+            entityId: null,
+            // A resource that does not OFFER search was refused by the registry, not by a policy,
+            // and the decision object would otherwise read `allow` on a denied entry.
+            decision: offered ? decision : denied(decision.permission, SKIPPED_FORBIDDEN),
+          }),
+        ),
+      );
       continue;
     }
+    // Neither of these is an authorization event: the resource is searchable in principle and has
+    // no text index or no repo to ask. They stay in `skipped` and out of the log.
     if (resource.searchFields.length === 0) {
       skipped.push({ entity: resource.name, reason: 'admin.search.skipped.no-text-fields' });
       continue;
@@ -112,8 +147,23 @@ export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchR
       continue;
     }
     searched.push(resource.name);
+    // Appended BEFORE the read, so a repo that throws still leaves the record that the rows were
+    // asked for — `audit.ts`: if it isn't logged, it didn't happen.
+    audit.push(
+      await ctx.audit.append({
+        requestId: ctx.requestId,
+        actor: ctx.actor,
+        operation: 'search',
+        kind: 'operation',
+        entity: resource.name,
+        entityId: null,
+        permission: decision.permission,
+        outcome: 'allowed',
+        reason: decision.reason,
+      }),
+    );
     hits.push(...(await searchResource(resource, term, limit)));
   }
 
-  return { term, hits, searched, skipped };
+  return { term, hits, searched, skipped, audit };
 }

package/src/widget-value.ts

@@ -92,7 +92,8 @@ export function assertMoney(field: AdminField, value: unknown): Money | null {
     return fail(
       field,
       `money value arrived as the number ${value}; money is integer minor units + an ISO currency`,
-      `store ${field.name} as { minor, currency } — x g migration "money ${field.entity}.${field.name}"`,
+      // `x db gen` writes migrations; `x g migration` is not a generator and never was.
+      `store ${field.name} as { minor, currency } — x db gen "change ${field.entity}.${field.name} to money"`,
     );
   }
   if (typeof value !== 'object') {