@ultimat3/admin 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,52 @@
+# @ultimat3/admin — boundary
+
+Tier 5. May import tiers 0–4. Exactly one importer: `@ultimat3/cli`, and only of `@ultimat3/admin/dev` — `cli → admin` is a declared sideways edge (`scripts/lib/tiers.ts`) so `x dev` can **mount** `/_x`. The root barrel `@ultimat3/admin` has no importer.
+
+Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev/index.ts`) = the `/_x` dev dashboard, `@ultimat3/admin` (`src/index.ts`) = the generated app admin (production, authz'd, AI-first). Keep them apart; nothing in `src/dev/` may be imported by an admin view, and the root barrel does not re-export the dev half — a host that mounts `/_x` (the CLI) must not load a Solid component to do it.
+
+## 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.
+- **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.
+- **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.
+- **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).
+- **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
+- **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
+- **A deliberate query loop declares itself.** `search.ts` runs one indexed lookup per text field on purpose — the query IR is a conjunction, so three small indexed reads beat one unindexed `OR` — and says so through `expectedQueryLoop()` from `@ultimat3/db` (tier 1, downward, and the only thing this package imports from it). That is the one suppression mechanism: never a comment pragma and never a list of exempt call sites. A new loop here either argues for itself in a `reason` or it is an N+1.
+- **The timeline panel renders the detector's verdicts, it does not re-derive them.** `repeatedSql` (`dev/panel-timeline.ts`) is a measurement over the trace this panel recorded — every SQL text seen twice. `nPlusOne` is the verdict: `x dev`'s statement ledger, read through `DevSources.statementLoops()` and scoped to the selected request, in the ledger's own order. A second count here would be blind to the `expectedQueryLoop` above and to statement attribution (`members.findById`, not raw SQL text), and would disagree with the `fix:` an author actually pastes. No detector wired → `null`, never `[]`: "nobody counted" is not "this request was clean".
+- **This catalog is the framework's one opt-OUT MCP surface, and that is deliberate.**
+  `mcp-tools.ts` is the only file that does not call `isMcpExposed` from `@ultimat3/core`: every
+  tool here is already gated on an admin permission, and the CRUD tools carry no `mcp` block at
+  all, so opting in would list `admin.posts.delete` while hiding the action button beside it.
+  `mcp: { expose: false }` withdraws one. Stated there, in core's `mcp-exposure.ts`, and in
+  `wiki/Admin-Dashboard.md` — a *second* exception anywhere is the bug.
+- **`dev/panel-db.ts`'s `sanitize` decides "did they type a statement", not "is it safe".** It blanks every opaque span in ONE left-to-right pass — `'…'`, `"…"`, `$tag$…$tag$` and both comment forms in a single alternation, because each form can contain another's opener — so `-- still typing` reads as an empty box. It used to feed a write-keyword scan in this file and that scan is gone; **do not cite it as a security property**. It once said an unterminated quote "leaves the rest visible — the guard fails closed": true of the scan it fed, meaningless now, and it never covered `$tag$` or slash-star, whose surviving character is `$` or `/`.
+- **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.
+- 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).
+- Colours only via `ThemeTokenRef` (`--x-*`). Raw hex does not typecheck.
+- Views are pure functions of props — no `createSignal`, no local state; the route owns it.
+
+## Layout
+
+| File | Owns |
+|---|---|
+| `admin.ts` | `defineAdmin` → resources, nav, route table, audit, authz |
+| `pages.ts` / `page-guard.tsx` | a `pages:` entry → route + nav item (pure) / the wrapper that decides before it renders |
+| `routes.ts` | the only `defineRoute` caller: mode per view, `policy` composed from the route's permissions |
+| `registry.ts` / `entity-columns.ts` | the entity surface the admin reads / one entity → column facts |
+| `resource.ts` / `fields.ts` / `widget-value.ts` | derivation, widget table, value guards |
+| `crud.ts` / `action-gate.ts` | policy → confirmation → validation → repo → audit |
+| `mcp-tools.ts` / `mcp.ts` | tool derivation (pure) / transport wiring |
+| `dev/server.ts` + `dev/panel-*.ts` | `/_x` mount guard and one panel per file |
+
+## Commands
+
+```bash
+bun test --filter @ultimat3/admin
+bun run --filter @ultimat3/admin typecheck
+```

package/README.md

@@ -32,7 +32,7 @@ import { devDashboard, defaultDevSources } from '@ultimat3/admin/dev';
 
 const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // throws in prod
 const response = await dev.handle(request); // null when the path is not /_x
-await dev.json('jobs'); // the same payload `x dev --panel jobs --json` prints
+await dev.json('jobs'); // the same payload /_x/jobs renders from
 ```
 
 The root barrel does not re-export any of this: `x dev` mounts `/_x` without pulling a Solid
@@ -58,9 +58,123 @@ export const admin = defineAdmin({
   audit: memoryAuditLog({ sinks: [auditTable] }),
 });
 
-export const routes = adminRoutes(admin); // every page `spa`, `network-only`, noindex
+export const routes = adminRoutes(admin); // generated views `spa`, custom pages `ssr`, all gated
 ```
 
+### The views are TSX, and the pieces come apart
+
+There is no view DSL here, and there will not be one. Every renderer is an ordinary SolidJS
+component in an ordinary `.tsx` file importing `@ultimat3/ui` — `AdminList`, `AdminForm`,
+`AdminDetail`, `Widget`, `AdminLayout` are each exported on their own, so a table can be lifted
+out of its page and dropped into a screen the generator never wrote:
+
+```tsx
+import { AdminList, AdminForm, Widget } from '@ultimat3/admin';
+
+<AdminList resource={admin.resource('posts')} page={page} ctx={ctx} … />;   // just the table
+<Widget field={field} value={row.total} ctx={ctx} mode="read" />;          // just one cell
+```
+
+`Widget` takes the field and the raw row value, not pre-derived props: `widgetProps()` is the
+guard (money is minor units, a timestamp has an IANA zone) and the component calls it, so there is
+no way to render a cell that skipped it. `mode` is `read` or `edit`; an edit cell also takes the
+`control` the surrounding `<Field>` hands its child, and `onInput`.
+
+An admin route is an ordinary `route` primitive; an admin action is an ordinary `action`. Nothing
+in this package is written in a second language that only the dashboard understands — the escape
+hatch is the same TSX as the main path, which is why there is no cliff to fall off when a screen
+stops being CRUD.
+
+### Custom pages
+
+The bespoke ops screen is the common case, not the corner: a reconciliation fixer, a proxy health
+board, a deploy button. Declare it in `pages:` and it becomes a real admin route.
+
+```tsx
+// admin/ops/page.tsx — a component, nothing framework-shaped about it
+export function OpsPage(props: AdminPageProps) {
+  return <OpsBoard counts={await mediaStateCounts()} />;
+}
+
+// admin/index.ts
+defineAdmin({
+  entities: [posts],
+  pages: [
+    {
+      path: '/ops',                       // rooted at basePath → /admin/ops
+      titleKey: 'admin.ops.title',
+      navGroup: 'admin.group.operations', // omit to keep it out of the nav
+      permissions: ['ops:read'],          // `admin:read` is composed in front of it
+      component: OpsPage,
+    },
+  ],
+  auth,
+});
+```
+
+| What you get | How |
+|---|---|
+| a row in `app.routes`, `adminRoutes()`, `x manifest` | `pageRoutes()` folds it in beside the generated screens |
+| a nav item that disappears for an actor who cannot open it | `NavItem.permissions` → `visibleNav` |
+| a `defineRoute({ policy })` you never wrote and cannot omit | `adminRouteConfig` composes `permissions[0]` into it |
+| a per-request refusal, audited, before your component runs | `guardedPage()` wraps it in `decideAll` |
+
+**The guard is not yours to remember.** `adminRoutes()` hands the router the *wrapped* component,
+never the one you wrote, and `AdminPageProps.ctx` is required by the type — a page component
+cannot be called without the handle the guard decides on. `permissions: []` throws
+`X_ADMIN_PAGE_UNGUARDED` where it is written, not on the first unauthenticated request. A path
+that shadows a generated screen throws `X_ADMIN_PAGE_PATH_INVALID` the same way.
+
+Custom pages are `render: 'ssr'`, `hydrate: 'never'`: the guard runs on the server, so there is no
+shell to ship and nothing to decide twice.
+
+### Serving an admin URL from your own route file
+
+A host whose router is file-based writes its own `page.tsx` for an admin URL. Take the gate from
+the route table — never type it a second time:
+
+```ts
+import { adminRouteFor } from '@ultimat3/admin';
+import { admin } from './admin';
+
+const route = adminRouteFor(admin, `${admin.basePath}/users`);
+
+export const config = defineRoute({
+  render: 'ssr',
+  hydrate: 'never',
+  offline: 'network-only',
+  policy: route.policy, // `defineAdmin()`'s, from `permissionsForOperation('users', 'list')`
+  meta: () => ({ title: t('admin.users.title') }),
+});
+```
+
+`route.policy` is the same object `route.config.policy` carries, so the gate has one declaration
+and one reader. A `path` the admin does not declare throws `X_ADMIN_PAGE_PATH_INVALID` listing the
+paths that would have worked — a page serving an admin URL the admin never built is a screen whose
+permissions nothing composed.
+
+### Splitting the admin across files
+
+`defineAdmin` takes **plain values** — `entities`, `resources`, `actions`, `jobs`, `pages`, `nav`,
+`branding`, `auth`, `audit`. Every one of them can be imported from its own module, so the cut is
+along the input's own keys and there is exactly one layout:
+
+```
+app/admin/
+  index.ts              defineAdmin({ … }) — composition only, no logic
+  auth.ts               actor() + policyAuthz({ policies })
+  nav.ts                groups, order, extras
+  <resource>/
+    resource.ts         the AdminResourceOptions entry (listFields, sensitive, labelField)
+    repo.ts             the AdminRepo binding
+    actions.ts          the AdminAction[] for this entity
+    pages/<name>.tsx    a custom page component for this entity, if any
+  pages/<name>.tsx      an app-wide custom page (ops, reconciliation, deploy)
+```
+
+`index.ts` imports each and composes. Nothing here is a framework rule — it is what the input
+shape already is, written down once so two apps do not invent two layouts. `x g admin` emits it.
+
 ### Derived from the entity, and only from it
 
 | Admin decision | Read from |
@@ -112,4 +226,4 @@ Panes are off until enabled, and `runAiPane` refuses (never no-ops) without a ru
 
 ## Errors
 
-`X_ADMIN_ENTITY_UNKNOWN` · `X_ADMIN_FIELD_UNSUPPORTED` · `X_ADMIN_POLICY_MISSING` · `X_DEV_DASHBOARD_IN_PROD` · `X_NOT_IMPLEMENTED` (an unwired `/_x` source, carrying the wiring line).
+`X_ADMIN_ENTITY_UNKNOWN` · `X_ADMIN_FIELD_UNSUPPORTED` · `X_ADMIN_POLICY_MISSING` · `X_ADMIN_PAGE_UNGUARDED` · `X_ADMIN_PAGE_PATH_INVALID` · `X_ADMIN_DENIED` · `X_ADMIN_TOOL_FORBIDDEN` · `X_ADMIN_INVALID` · `X_DEV_DASHBOARD_IN_PROD` · `X_NOT_IMPLEMENTED` (an unwired `/_x` source, carrying the wiring line).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -31,18 +32,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "1.2.0",
-    "@ultimat3/ai": "1.2.0",
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/entity": "1.2.0",
-    "@ultimat3/i18n": "1.2.0",
-    "@ultimat3/jobs": "1.2.0",
-    "@ultimat3/mcp": "1.2.0",
-    "@ultimat3/money": "1.2.0",
-    "@ultimat3/policy": "1.2.0",
-    "@ultimat3/query": "1.2.0",
-    "@ultimat3/render": "1.2.0",
-    "@ultimat3/ui": "1.2.0"
+    "@ultimat3/action": "2.0.0",
+    "@ultimat3/ai": "2.0.0",
+    "@ultimat3/cache": "2.0.0",
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/db": "2.0.0",
+    "@ultimat3/entity": "2.0.0",
+    "@ultimat3/i18n": "2.0.0",
+    "@ultimat3/jobs": "2.0.0",
+    "@ultimat3/mcp": "2.0.0",
+    "@ultimat3/money": "2.0.0",
+    "@ultimat3/policy": "2.0.0",
+    "@ultimat3/query": "2.0.0",
+    "@ultimat3/render": "2.0.0",
+    "@ultimat3/schema": "2.0.0",
+    "@ultimat3/ui": "2.0.0"
   }
 }

package/src/admin.ts

@@ -6,7 +6,8 @@ import { type AuditLog, memoryAuditLog } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
 import type { CrudCtx } from './crud';
 import { permissionsForOperation } from './crud';
-import { adminNav, type NavGroup, type NavOptions, visibleNav } from './nav';
+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';
 import type { AdminAction, AdminEntity, AdminJobSummary, AdminRow } from './registry';
 import {
@@ -31,7 +32,9 @@ export type AdminView =
   | 'search'
   | 'jobs'
   | 'audit'
-  | 'dashboard';
+  | 'dashboard'
+  /** A `pages:` entry: the app's own component, guarded by the frame. */
+  | 'page';
 
 /**
  * A route as data. `routes.ts` turns these into `defineRoute()` configs; keeping the table
@@ -43,6 +46,11 @@ export interface AdminRoute {
   readonly entity: string | null;
   readonly titleKey: string;
   readonly permissions: readonly string[];
+  /**
+   * Set only on `view: 'page'`. It is the AUTHOR's component, still unguarded — `routes.ts` is
+   * the only thing that may hand it out, and it hands out the wrapped one.
+   */
+  readonly component?: AdminPageComponent;
 }
 
 export interface DefineAdminInput {
@@ -52,6 +60,8 @@ export interface DefineAdminInput {
   /** Registered actions. Each is attached to `action.entity`, or the global toolbar. */
   readonly actions?: readonly AdminAction[];
   readonly jobs?: readonly AdminJobSummary[];
+  /** Screens the generator would never write. Declared here so they are not a second surface. */
+  readonly pages?: readonly AdminCustomPage[];
   readonly nav?: NavOptions;
   readonly branding?: Partial<AdminBranding>;
   readonly auth: AdminAuth;
@@ -80,7 +90,7 @@ export interface AdminApp {
 }
 
 const VIEW_OPERATION: Readonly<
-  Record<Exclude<AdminView, 'jobs' | 'audit' | 'dashboard'>, AdminOperation>
+  Record<Exclude<AdminView, 'jobs' | 'audit' | 'dashboard' | 'page'>, AdminOperation>
 > = {
   list: 'list',
   detail: 'detail',
@@ -92,7 +102,10 @@ const VIEW_OPERATION: Readonly<
 function resourceRoutes(basePath: string, resource: AdminResource): readonly AdminRoute[] {
   const base = `${basePath}${resource.path}`;
   const routes: AdminRoute[] = [];
-  const add = (view: Exclude<AdminView, 'jobs' | 'audit' | 'dashboard'>, path: string): void => {
+  const add = (
+    view: Exclude<AdminView, 'jobs' | 'audit' | 'dashboard' | 'page'>,
+    path: string,
+  ): void => {
     const op = VIEW_OPERATION[view];
     if (!resource.operations.includes(op)) return;
     routes.push({
@@ -128,8 +141,14 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     });
   });
 
-  const nav = adminNav(resources, input.nav ?? {});
-  const routes: AdminRoute[] = [
+  const pages = input.pages ?? [];
+  const navOptions = input.nav ?? {};
+  const extra: readonly (NavItem & { readonly group: string })[] = [
+    ...(navOptions.extra ?? []),
+    ...pageNavItems(pages),
+  ];
+  const nav = adminNav(resources, { ...navOptions, extra });
+  const generated: AdminRoute[] = [
     {
       path: basePath,
       view: 'dashboard',
@@ -161,6 +180,16 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     ...resources.flatMap((resource) => resourceRoutes(basePath, resource)),
   ];
 
+  // Generated first, so a page that would shadow one is refused rather than deciding a race.
+  const routes: readonly AdminRoute[] = [
+    ...generated,
+    ...pageRoutes(
+      basePath,
+      pages,
+      generated.map((route) => route.path),
+    ),
+  ];
+
   return {
     basePath,
     branding,

package/src/crud.ts

@@ -41,8 +41,13 @@ export type CrudResult<Row extends AdminRow> =
     };
 
 export type ListResult<Row extends AdminRow> =
-  | { readonly ok: true; readonly page: AdminPage<Row> }
-  | { readonly ok: false; readonly kind: 'denied'; readonly decision: AdminDecision };
+  | { readonly ok: true; readonly page: AdminPage<Row>; readonly audit: AuditEntry }
+  | {
+      readonly ok: false;
+      readonly kind: 'denied';
+      readonly decision: AdminDecision;
+      readonly audit: AuditEntry;
+    };
 
 /** Both gates, always in this order: the admin-level one, then the entity-level one. */
 export function permissionsForOperation(entity: string, op: AdminOperation): readonly string[] {
@@ -96,14 +101,38 @@ async function refuse<Row extends AdminRow>(
   };
 }
 
+/**
+ * The one read that logged nothing, in either direction: `audit.ts` says denied and failed attempts
+ * are logged too, and `adminDetail` below logs the allowed read as well — so a listing that walked
+ * every row of a table left no trace, and a refused listing left no trace of the refusal either.
+ * There is no `entityId`: the subject is the table, not a row.
+ */
 export async function adminList<Row extends AdminRow>(
   resource: AdminResource<Row>,
   ctx: CrudCtx,
   req: PageRequest = {},
 ): Promise<ListResult<Row>> {
   const decision = decideOperation(resource, 'list', ctx);
-  if (!decision.allowed) return { ok: false, kind: 'denied', decision };
-  return { ok: true, page: await fetchPage(resource, req) };
+  if (!decision.allowed) {
+    const refused = await refuse(resource, 'list', ctx, decision, null);
+    return { ok: false, kind: 'denied', decision, audit: refused.audit };
+  }
+  const page = await fetchPage(resource, req);
+  return {
+    ok: true,
+    page,
+    audit: await ctx.audit.append({
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: 'list',
+      kind: 'operation',
+      entity: resource.name,
+      entityId: null,
+      permission: decision.permission,
+      outcome: 'allowed',
+      reason: decision.reason,
+    }),
+  };
 }
 
 export async function adminDetail<Row extends AdminRow>(

package/src/detail.tsx

@@ -49,7 +49,10 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
       <ErrorState
         error={adminErrorFrom({
           code: 'X_ADMIN_ENTITY_UNKNOWN',
-          cause: t('admin.detail.not-found', { entity: props.resource.name }),
+          // `.cause`, not a bare `admin.detail.not-found`: a catalog is authored nested and
+          // `parseNestedCatalog` refuses a dot inside a key, so a name is a leaf or a branch and
+          // never both — `admin.detail.not-found` + `.fix` could not have coexisted in en.json.
+          cause: t('admin.detail.not-found.cause', { entity: props.resource.name }),
           fix: t('admin.detail.not-found.fix'),
         })}
       />

package/src/dev/data.ts

@@ -11,6 +11,7 @@ import type { JobState, StepStatus } from '@ultimat3/jobs';
 import type { AdminActor, AdminAuthz } from '../authz';
 import { DevSourceUnavailableError } from '../errors';
 import type {
+  BackfillFact,
   CacheEdgeFact,
   DevSources,
   DriftFact,
@@ -27,6 +28,7 @@ import type {
   RequestTrace,
   RouteFact,
   SqlResult,
+  StatementLoopFact,
   TableFact,
   TaskFact,
 } from './facts';
@@ -38,11 +40,14 @@ export function staticDevSources(facts: Partial<DevSources> = {}): DevSources {
   return {
     routes: facts.routes ?? ((): Promise<readonly RouteFact[]> => empty([])),
     traces: facts.traces ?? ((): Promise<readonly RequestTrace[]> => empty([])),
+    statementLoops:
+      facts.statementLoops ?? ((): Promise<readonly StatementLoopFact[]> => empty([])),
     liveQueries: facts.liveQueries ?? ((): Promise<readonly LiveQueryFact[]> => empty([])),
     subscribers: facts.subscribers ?? ((): Promise<readonly LiveSubscriberFact[]> => empty([])),
     jobDefs: facts.jobDefs ?? ((): Promise<readonly JobDefFact[]> => empty([])),
     queues: facts.queues ?? ((): Promise<readonly QueueFact[]> => empty([])),
     jobRuns: facts.jobRuns ?? ((): Promise<readonly JobRunFact[]> => empty([])),
+    backfills: facts.backfills ?? ((): Promise<readonly BackfillFact[]> => empty([])),
     tasks: facts.tasks ?? ((): Promise<readonly TaskFact[]> => empty([])),
     tables: facts.tables ?? ((): Promise<readonly TableFact[]> => empty([])),
     drift: facts.drift ?? ((): Promise<readonly DriftFact[]> => empty([])),
@@ -80,6 +85,13 @@ export interface DevSourceOptions {
    * wiring line, rather than rendering an empty panel that reads as "nothing happened".
    */
   readonly hooks?: Partial<DevSources>;
+  /**
+   * Sample input per query name, so the live panel can show the SQL a query actually compiles
+   * to. `@ultimat3/query`'s `QueryDescriptor` carries no SQL text — it depends on the input —
+   * so a query with no sample here stays `sql: null` rather than an invented guess. `x dev
+   * --actor` supplies these the same way it supplies `actors` for the policy matrix.
+   */
+  readonly sqlSamples?: Readonly<Record<string, unknown>>;
 }
 
 const unavailable = (source: string, panel: string): DevSourceUnavailableError =>
@@ -96,13 +108,22 @@ const unwired = <T>(source: string, panel: string): (() => Promise<T>) => {
 /** How many recent runs the jobs panel traces. A dev panel reads, it does not page. */
 const RUN_WINDOW = 50;
 
-/** `JobState` and `StepStatus` are the queue's vocabulary; the panel renders its own. */
+/**
+ * `JobState` and `StepStatus` are the queue's vocabulary; the panel renders its own.
+ *
+ * `cancelled` is `ok` and not `dead`, because the panel's four words split on "did this need
+ * attention", not on "did the handler run". `panel-jobs.ts` reads `dead` as the dead-letter list
+ * and `failed | dead` as the needs-attention list — a job an operator stopped on purpose belongs
+ * in neither, and filing it under `dead` would put `x jobs retry` in front of a reader as the
+ * remedy for a cancellation nobody wants resurrected.
+ */
 const RUN_STATUS: Readonly<Record<JobState, JobRunFact['status']>> = {
   ready: 'running',
   delayed: 'running',
   running: 'running',
   suspended: 'running',
   done: 'ok',
+  cancelled: 'ok',
   failed: 'failed',
   dead: 'dead',
 };
@@ -146,19 +167,35 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
 
     traces: unwired<readonly RequestTrace[]>('traces', 'timeline'),
 
+    // The verdicts belong to the one statement ledger `x dev` installs, so a host without it
+    // refuses here rather than answering `[]`: an empty list claims "no N+1 in this request",
+    // which is a different and unearned answer — the same argument `subscribers` and `mail` make.
+    statementLoops: unwired<readonly StatementLoopFact[]>('statementLoops', 'timeline'),
+
     async liveQueries(): Promise<readonly LiveQueryFact[]> {
-      const { describeQueries } = await import('@ultimat3/query');
-      return listOf(describeQueries()).map((raw) => {
+      const { describeQueries, describeSql, listQueries } = await import('@ultimat3/query');
+      const queries = describeQueries();
+      // `describeSql` is the one place that actually compiles a query to text — it needs a
+      // sample input to do it, so a name with no entry in `sqlSamples` comes back `sql: null`
+      // rather than the permanently-empty string this source used to answer for every query.
+      // It takes the live `AnyQuery[]` targets (`listQueries()`), never the already-projected
+      // `QueryDescriptor[]` this method also needs for `name`/`live`/`capability`.
+      const sqlByName = new Map(
+        (await describeSql(opts.sqlSamples ?? {}, listQueries())).map((entry) => [
+          entry.query,
+          entry.sql,
+        ]),
+      );
+      return listOf(queries).map((raw) => {
         const query = bagOf(raw);
+        const name = str(query['name']);
         return {
-          name: str(query['name']),
+          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']),
-          // `QueryDescriptor` carries no SQL text at all; this stays blank until the query
-          // registry actually describes one — never invent a value here.
-          sql: str(query['sql']),
+          sql: sqlByName.get(name) ?? null,
         };
       });
     },
@@ -227,6 +264,31 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         }));
     },
 
+    /**
+     * The whole ledger, newest first — not just the passes in flight. `x jobs ls` reports the live
+     * queue and says so; a panel is read to answer "has this backfill ever run here, and what did
+     * it sweep", and the completed rows ARE that answer.
+     *
+     * `inspectBackfills` returns `[]` for a driver that ships no ledger, so only a process with no
+     * queue at all refuses here — which is the same line `queues` and `jobRuns` draw.
+     */
+    async backfills(): Promise<readonly BackfillFact[]> {
+      const { inspectBackfills, jobDriver } = await import('@ultimat3/jobs');
+      const driver = jobDriver();
+      if (driver === undefined) throw unavailable('backfills', 'jobs');
+      return (await inspectBackfills(driver)).map((pass) => ({
+        runId: pass.runId,
+        name: pass.name,
+        status: pass.status,
+        rows: pass.rows,
+        cursor: pass.cursor,
+        startedAt: pass.startedAt,
+        completedAt: pass.completedAt,
+        durationMs: pass.durationMs,
+        appVersion: pass.appVersion,
+      }));
+    },
+
     async tasks(): Promise<readonly TaskFact[]> {
       const { inspectManifest } = await import('@ultimat3/jobs');
       return inspectManifest().tasks.map((task) => ({

package/src/dev/facts.ts

@@ -39,6 +39,28 @@ export interface RequestTrace {
   readonly spans: readonly TimelineSpan[];
 }
 
+/**
+ * One statement shape repeated inside one request past the detector's threshold — a verdict,
+ * already carrying the error a host renders. The count, the attribution and the suppression rule
+ * are the detector's (`x dev`'s statement ledger); nothing here re-derives them from the spans,
+ * because a second count blind to `expectedQueryLoop` would disagree with the one that warns.
+ */
+export interface StatementLoopFact {
+  /** The request the loop happened in — how a trace and its verdicts are matched up. */
+  readonly requestId: string;
+  /** `X_N_PLUS_ONE_QUERY` or `X_N_PLUS_ONE_WRITE`. */
+  readonly code: string;
+  readonly cause: string;
+  /** Runnable, and the whole point: the `preload`/`insertAll` line that ends the loop. */
+  readonly fix: string;
+  readonly docs: string | null;
+  /** What repeated: `members.findById` when a repository sent it, else the statement's own text. */
+  readonly subject: string;
+  readonly count: number;
+  /** One of the statements, verbatim. */
+  readonly sample: string;
+}
+
 export interface LiveSubscriberFact {
   readonly id: string;
   readonly query: string;
@@ -54,7 +76,8 @@ export interface LiveQueryFact {
   readonly name: string;
   readonly live: boolean;
   readonly policy: string;
-  readonly sql: string;
+  /** `null` when no sample input was supplied for this query — SQL depends on arguments. */
+  readonly sql: string | null;
 }
 
 export interface JobDefFact {
@@ -97,6 +120,28 @@ export interface TaskFact {
   readonly nextRunAt: string | null;
 }
 
+/**
+ * One `x_backfills` pass. The queue's own facts answer "is this job moving"; only the ledger
+ * answers "how much of the table is behind it", which is the one question a sweep is watched for.
+ * `cursor` is where the pass had got to and `null` before its first batch — never a percentage:
+ * nothing counted the rows ahead of it, and a made-up denominator is the fact this panel exists
+ * not to invent.
+ */
+export interface BackfillFact {
+  /** The pass, and the run id of the job sweeping it — the join back to `runs` on this panel. */
+  readonly runId: string;
+  readonly name: string;
+  readonly status: 'running' | 'completed' | 'failed';
+  readonly rows: number;
+  readonly cursor: string | null;
+  readonly startedAt: string;
+  readonly completedAt: string | null;
+  /** How long the pass took. `null` while it is still running. */
+  readonly durationMs: number | null;
+  /** The build that STARTED the pass — a redeploy mid-sweep does not rewrite it. */
+  readonly appVersion: string;
+}
+
 export interface ColumnFact {
   readonly name: string;
   readonly type: string;
@@ -163,11 +208,13 @@ export interface ManifestFact {
 export interface DevSources {
   routes(): Promise<readonly RouteFact[]>;
   traces(): Promise<readonly RequestTrace[]>;
+  statementLoops(): Promise<readonly StatementLoopFact[]>;
   liveQueries(): Promise<readonly LiveQueryFact[]>;
   subscribers(): Promise<readonly LiveSubscriberFact[]>;
   jobDefs(): Promise<readonly JobDefFact[]>;
   queues(): Promise<readonly QueueFact[]>;
   jobRuns(): Promise<readonly JobRunFact[]>;
+  backfills(): Promise<readonly BackfillFact[]>;
   tasks(): Promise<readonly TaskFact[]>;
   tables(): Promise<readonly TableFact[]>;
   drift(): Promise<readonly DriftFact[]>;

package/src/dev/index.ts

@@ -5,6 +5,7 @@
 
 export { type DevSourceOptions, defaultDevSources, staticDevSources } from './data';
 export type {
+  BackfillFact,
   CacheEdgeFact,
   ColumnFact,
   DevSources,
@@ -23,6 +24,7 @@ export type {
   RouteFact,
   SpanKind,
   SqlResult,
+  StatementLoopFact,
   TableFact,
   TaskFact,
   TimelineSpan,
@@ -44,4 +46,5 @@ export {
   type DevDashboard,
   type DevDashboardOptions,
   devDashboard,
+  devShellStyle,
 } from './server';