@ultimat3/admin 1.2.0 → 3.0.0

package/src/dev/panel-cache.ts

@@ -19,8 +19,8 @@ export interface CachePanelData {
 
 export const cachePanel: DevPanel<CachePanelData> = {
   key: 'cache',
-  titleKey: 'dev.panel.cache',
-  question: 'what invalidated what — and why is this still stale?',
+  titleKey: 'dev.panel.cache.title',
+  questionKey: 'dev.panel.cache.question',
   async data(sources): Promise<CachePanelData> {
     const graph = await sources.cacheGraph();
     // The invalidation log needs a running process that has served a write; the graph alone

package/src/dev/panel-db.ts

@@ -2,6 +2,8 @@
 // Kills: "what is actually in the table, and does it match the migrations?" — psql in a tab,
 // read-only by default, plus the schema diff against the migration history.
 
+import { isUltimateError } from '@ultimat3/core';
+import { assertReadOnlyQuery } from '@ultimat3/mcp';
 import type { DriftFact, SqlResult, TableFact } from './facts';
 import type { DevPanel } from './panel';
 
@@ -15,30 +17,83 @@ export interface DbPanelData {
   readonly readOnly: boolean;
 }
 
-const WRITE_STATEMENT =
-  /\b(insert|update|delete|drop|alter|truncate|create|grant|revoke|copy|vacuum)\b/i;
+/**
+ * Every span Postgres reads as opaque text rather than as SQL, in ONE alternation: a `'…'`
+ * string (`''` escapes included), a `"…"` quoted identifier (`""` included), a `$tag$…$tag$`
+ * dollar-quoted body, a `--` line comment and a slash-star block comment.
+ *
+ * One pass, not five. Sequential passes cannot be ordered correctly, because each form can
+ * contain the opener of any other: blanking comments first eats the `--` inside `'…'`, and
+ * blanking strings first eats the `'` inside a comment. A single left-to-right scan resolves
+ * that the way a lexer does — whichever token *starts* first consumes the rest.
+ *
+ * This is NO LONGER a security scan and must not be read as one. It once fed a write-keyword
+ * check in this file; that check is gone and `assertReadOnlyQuery` owns the question. All this
+ * decides now is "did the developer type a statement, or only a comment".
+ */
+const OPAQUE_SPAN =
+  /'(?:[^']|'')*'|"(?:[^"]|"")*"|\$([A-Za-z_]\w*)?\$[\s\S]*?\$\1\$|--[^\n]*|\/\*[\s\S]*?\*\//g;
+
+/**
+ * Blanks every comment and literal so `-- still typing` and `/* … *​/` read as an empty box
+ * rather than as a refusal. Blanked to spaces, never deleted, so `whe`+`re` never fuses into a
+ * new word.
+ *
+ * Says NOTHING about whether the statement is safe, and in particular nothing about an
+ * unterminated delimiter: this regex simply fails to match one, which used to be described here
+ * as failing closed. It was — for a keyword scan that no longer exists. `assertReadOnlyQuery` is
+ * what refuses an unterminated delimiter now, in all five forms.
+ */
+function sanitize(sql: string): string {
+  return sql.replace(OPAQUE_SPAN, (span) => ' '.repeat(span.length));
+}
 
 /**
  * Read-only is enforced here, not just in the UI: /_x runs with the developer's own DB
  * credentials, so "the textarea only sends SELECTs" would be the whole safety story.
  * `x db psql --write` is the deliberate way out.
+ *
+ * ONE implementation of "is this a read", and it is `@ultimat3/mcp`'s. That guard refuses four
+ * things this file's own keyword scan never did — a batch of statements, a call into the
+ * `pg_read_*`/`pg_advisory_*`/`pg_sleep`/`set_config` families (a prefix, so a member Postgres adds
+ * next release is refused on the day it ships), `FOR UPDATE`, and a delimiter that never closes in
+ * any of its five forms (`'`, `E'`, `"`, `$tag$`, slash-star) — and a second, weaker copy of a
+ * security rule is how the two drift apart. Downward, not sideways: `admin` is tier 5, `mcp` is
+ * tier 4, and `@ultimat3/mcp` is already a dependency of this package (`src/mcp.ts`).
+ *
+ * NOTHING about the verdict stays local, deliberately. A local unterminated-delimiter refusal
+ * lived here for one revision and was deleted: it tested for a surviving `'` or `"`, so it caught
+ * three of the five forms and let `select $tag$ ; delete from members` fall through to the shared
+ * guard — one failure mode with two different explanations, the local one calling a dollar-quoted
+ * body "a quote". A second detector for a property the guard below already owns and tests is the
+ * drift this delegation exists to remove.
+ *
+ * What stays local is the emptiness test and the WAY OUT: `@ultimat3/mcp` tells its caller to
+ * expose an action, which is not advice a developer standing at `/_x` can act on. Only this file
+ * knows which reader it is talking to.
  */
 export function assertReadOnly(sql: string): string | null {
-  const stripped = sql.replace(/--[^\n]*/g, ' ').trim();
-  if (stripped === '') return null;
-  if (WRITE_STATEMENT.test(stripped)) {
-    return `refused: the /_x DB panel is read-only. Run it with: x db psql --write`;
-  }
-  if (!/^(select|with|explain|show|table)\b/i.test(stripped)) {
-    return 'refused: only SELECT / WITH / EXPLAIN / SHOW / TABLE statements run here';
+  // Nothing to run — a blank box or a comment the developer is still writing, not a refusal.
+  if (sanitize(sql).trim() === '') return null;
+  try {
+    assertReadOnlyQuery(sql);
+    return null;
+  } catch (error) {
+    // Structurally, never `String(error)`: the guard throws an `UltimateError` whose `cause` is
+    // the sentence a developer needs, and anything else here is a bug in the guard, not a verdict.
+    if (!isUltimateError(error)) throw error;
+    // Two classes arrive through one code, and the panel cannot tell them apart without reading
+    // another package's prose — so the way out is phrased to be true for both. It used to assert
+    // `Run it with: x db psql --write`, which is the wrong instruction for a missing quote: that
+    // flag grants writes, it does not close a delimiter.
+    return `refused: ${error.cause}. Fix the statement, or — if it is meant to write — run it with: x db psql --write`;
   }
-  return null;
 }
 
 export const dbPanel: DevPanel<DbPanelData> = {
   key: 'db',
-  titleKey: 'dev.panel.db',
-  question: 'what is in the table, and does the schema match the migrations?',
+  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()]);
     const sql = params.get('sql');

package/src/dev/panel-jobs.ts

@@ -2,7 +2,7 @@
 // Kills: "is the queue moving, and which step failed?" — queue depth, per-run step traces,
 // the retry-from-step target, and the dead letter.
 
-import type { JobDefFact, JobRunFact, QueueFact, TaskFact } from './facts';
+import type { BackfillFact, JobDefFact, JobRunFact, QueueFact, TaskFact } from './facts';
 import type { DevPanel } from './panel';
 
 export interface RetryTarget {
@@ -22,6 +22,14 @@ export interface JobsPanelData {
   readonly deadLetter: readonly JobRunFact[];
   readonly retryTargets: readonly RetryTarget[];
   readonly totalDepth: number;
+  /** Every pass the `x_backfills` ledger holds, newest first — see `backfillsInFlight`. */
+  readonly backfills: readonly BackfillFact[];
+  /**
+   * The sweeps still going, split out rather than left for the reader to filter: a `?queue=`
+   * filter scopes the runs on this panel and a backfill is not a queue, so the one number that
+   * would otherwise be missed is how many passes are moving right now.
+   */
+  readonly backfillsInFlight: number;
 }
 
 const firstFailedStep = (run: JobRunFact): RetryTarget | null => {
@@ -38,14 +46,15 @@ const firstFailedStep = (run: JobRunFact): RetryTarget | null => {
 
 export const jobsPanel: DevPanel<JobsPanelData> = {
   key: 'jobs',
-  titleKey: 'dev.panel.jobs',
-  question: 'is the queue moving, and which step failed?',
+  titleKey: 'dev.panel.jobs.title',
+  questionKey: 'dev.panel.jobs.question',
   async data(sources, params): Promise<JobsPanelData> {
-    const [queues, jobs, tasks, runs] = await Promise.all([
+    const [queues, jobs, tasks, runs, backfills] = await Promise.all([
       sources.queues(),
       sources.jobDefs(),
       sources.tasks(),
       sources.jobRuns(),
+      sources.backfills(),
     ]);
     const queueFilter = params.get('queue');
     const scoped = queueFilter === null ? runs : runs.filter((run) => run.queue === queueFilter);
@@ -61,6 +70,8 @@ export const jobsPanel: DevPanel<JobsPanelData> = {
         .map(firstFailedStep)
         .filter((target): target is RetryTarget => target !== null),
       totalDepth: queues.reduce((sum, queue) => sum + queue.depth, 0),
+      backfills,
+      backfillsInFlight: backfills.filter((pass) => pass.status === 'running').length,
     };
   },
 };

package/src/dev/panel-live.ts

@@ -2,6 +2,7 @@
 // Kills: "why did (or didn't) this subscriber get that row?" — every subscriber, what it
 // received, and the matcher's decision trace beside it.
 
+import { DevSourceUnavailableError } from '../errors';
 import type { LiveQueryFact, LiveSubscriberFact } from './facts';
 import type { DevPanel } from './panel';
 
@@ -21,13 +22,27 @@ export interface LivePanelData {
 
 export const livePanel: DevPanel<LivePanelData> = {
   key: 'live',
-  titleKey: 'dev.panel.live',
-  question: 'what does each subscriber receive, and why?',
+  titleKey: 'dev.panel.live.title',
+  questionKey: 'dev.panel.live.question',
   async data(sources, params): Promise<LivePanelData> {
     const queries = (await sources.liveQueries()).filter((query) => query.live);
     // The subscriber list needs a running sync node; without one the panel still shows the
-    // registered live queries rather than an empty tab.
-    const subscribers = await sources.subscribers().catch((): readonly LiveSubscriberFact[] => []);
+    // registered live queries rather than an empty tab. `wired` is kept apart from the list
+    // itself: `[]` is what a *running* node with nobody attached answers too, and folding the
+    // two into one empty array made a genuinely idle live tier print "no sync node" — the same
+    // "an empty list is not the same answer as no detector" argument `panel-timeline.ts` makes.
+    let subscribers: readonly LiveSubscriberFact[] = [];
+    let wired = true;
+    try {
+      subscribers = await sources.subscribers();
+    } catch (error) {
+      // Only the one error that MEANS unwired. A bare `catch` read an authz refusal, a dropped
+      // NATS connection and a bug in the recorder as "no sync node" — the note the panel prints
+      // for a tier that was never installed — and threw the diagnostic away. Anything else
+      // reaches `panelPayload`, which renders its code and its fix line.
+      if (!(error instanceof DevSourceUnavailableError)) throw error;
+      wired = false;
+    }
     const wanted = params.get('query');
     const scoped =
       wanted === null ? subscribers : subscribers.filter((sub) => sub.query === wanted);
@@ -40,7 +55,7 @@ export const livePanel: DevPanel<LivePanelData> = {
       rejected: scoped
         .filter((sub) => !sub.matched)
         .map((sub) => ({ id: sub.id, query: sub.query, trace: sub.trace })),
-      note: subscribers.length === 0 ? 'dev.live.no-sync-node' : null,
+      note: wired ? null : 'dev.live.no-sync-node',
     };
   },
 };

package/src/dev/panel-mail.ts

@@ -18,8 +18,8 @@ export interface MailPanelData {
 
 export const mailPanel: DevPanel<MailPanelData> = {
   key: 'mail',
-  titleKey: 'dev.panel.mail',
-  question: 'what did that email look like, in that locale?',
+  titleKey: 'dev.panel.mail.title',
+  questionKey: 'dev.panel.mail.question',
   async data(sources, params): Promise<MailPanelData> {
     const all = await sources.mail();
     const locale = params.get('locale');

package/src/dev/panel-manifest.ts

@@ -17,8 +17,8 @@ export interface ManifestPanelData {
 
 export const manifestPanel: DevPanel<ManifestPanelData> = {
   key: 'manifest',
-  titleKey: 'dev.panel.manifest',
-  question: 'is the committed x.manifest.json current?',
+  titleKey: 'dev.panel.manifest.title',
+  questionKey: 'dev.panel.manifest.question',
   async data(sources): Promise<ManifestPanelData> {
     const manifest = await sources.manifest();
     return {

package/src/dev/panel-policy.ts

@@ -24,8 +24,8 @@ export interface PolicyPanelData {
 
 export const policyPanel: DevPanel<PolicyPanelData> = {
   key: 'policy',
-  titleKey: 'dev.panel.policy',
-  question: 'can this actor do that, and why?',
+  titleKey: 'dev.panel.policy.title',
+  questionKey: 'dev.panel.policy.question',
   async data(sources, params): Promise<PolicyPanelData> {
     const facts = await sources.policyMatrix();
     const actors = [...new Set(facts.map((fact) => fact.actorId))].sort();

package/src/dev/panel-routes.ts

@@ -23,8 +23,8 @@ const kb = (budget: string | undefined): number => {
 
 export const routesPanel: DevPanel<RoutesPanelData> = {
   key: 'routes',
-  titleKey: 'dev.panel.routes',
-  question: 'which handler serves this?',
+  titleKey: 'dev.panel.routes.title',
+  questionKey: 'dev.panel.routes.question',
   async data(sources): Promise<RoutesPanelData> {
     const routes = await sources.routes();
     const byRenderMode: Record<string, number> = {};

package/src/dev/panel-timeline.ts

@@ -1,8 +1,9 @@
 // Panel: Request timeline.
 // Kills: "where did the 800ms go?" — a flamegraph of one request: SQL, cache hits, action
-// calls, and policy decisions on one axis, with the N+1 already counted for you.
+// calls, and policy decisions on one axis, with the N+1 already counted for you — counted by
+// `x dev`'s statement ledger and read here through `statementLoops()`, never re-derived.
 
-import type { RequestTrace, SpanKind, TimelineSpan } from './facts';
+import type { RequestTrace, SpanKind, StatementLoopFact, TimelineSpan } from './facts';
 import type { DevPanel } from './panel';
 
 export interface FlameRow {
@@ -22,8 +23,18 @@ export interface TimelinePanelData {
   readonly selected: RequestTrace | null;
   readonly flame: readonly FlameRow[];
   readonly totalsByKind: Readonly<Record<string, number>>;
-  /** Same SQL text more than once in one request. The N+1 detector. */
+  /** Same SQL text more than once in one request. A measurement over this trace, not a verdict. */
   readonly repeatedSql: readonly { readonly sql: string; readonly count: number }[];
+  /**
+   * The detector's verdicts for the selected request, or `null` when no detector is installed.
+   *
+   * Two fields and not one, deliberately: `repeatedSql` above is a **measurement** over the trace
+   * this panel recorded — every SQL text that appeared twice, whatever it was — while this is the
+   * **verdict**, counted per request by `x dev`'s statement ledger with attribution applied and
+   * `expectedQueryLoop` honoured. A measurement that started warning would be a second detector,
+   * disagreeing with the one whose `fix:` an author actually pastes.
+   */
+  readonly nPlusOne: readonly StatementLoopFact[] | null;
 }
 
 function flatten(trace: RequestTrace): readonly FlameRow[] {
@@ -48,13 +59,17 @@ function flatten(trace: RequestTrace): readonly FlameRow[] {
 
 export const timelinePanel: DevPanel<TimelinePanelData> = {
   key: 'timeline',
-  titleKey: 'dev.panel.timeline',
-  question: 'where did the time go in this request?',
+  titleKey: 'dev.panel.timeline.title',
+  questionKey: 'dev.panel.timeline.question',
   async data(sources, params): Promise<TimelinePanelData> {
     const traces = await sources.traces();
     const wanted = params.get('requestId');
     const selected =
       (wanted === null ? traces[0] : traces.find((trace) => trace.requestId === wanted)) ?? null;
+    // Degrade rather than reject, as `panel-live.ts` does for `subscribers`: a host with traces
+    // but no detector installed must still get its flamegraph. `null` carries that difference —
+    // "nobody counted" is not "counted, and this request was clean".
+    const loops = await sources.statementLoops().catch((): null => null);
 
     const totalsByKind: Record<string, number> = {};
     const sqlCounts = new Map<string, number>();
@@ -77,6 +92,12 @@ export const timelinePanel: DevPanel<TimelinePanelData> = {
         .filter(([, count]) => count > 1)
         .map(([sql, count]) => ({ sql, count }))
         .sort((a, b) => b.count - a.count),
+      // Scoped to the shown request and left in the ledger's own order — it already orders
+      // newest first, and a second sort here would be this panel deciding what matters most.
+      // With nothing selected the match is against `undefined`, so the answer is `[]`: no
+      // request is on screen to have looped.
+      nPlusOne:
+        loops === null ? null : loops.filter((loop) => loop.requestId === selected?.requestId),
     };
   },
 };

package/src/dev/panel.ts

@@ -5,11 +5,15 @@
 import type { DevSources } from './facts';
 
 export interface DevPanel<Data = unknown> {
-  /** URL segment and `--json` selector: `x dev --panel routes --json`. */
+  /** URL segment under `/_x`, and the key `devDashboard().json(key)` takes. */
   readonly key: string;
   readonly titleKey: string;
-  /** The question this panel exists to kill. Rendered as the tab's subtitle. */
-  readonly question: string;
+  /**
+   * i18n key for the question this panel exists to kill, rendered as the tab's subtitle —
+   * `t(questionKey)`, never a literal sitting beside `titleKey`. The two are siblings under the
+   * panel's own namespace: `dev.panel.jobs.title` and `dev.panel.jobs.question`.
+   */
+  readonly questionKey: string;
   data(sources: DevSources, params: URLSearchParams): Promise<Data>;
 }
 

package/src/dev/server.ts

@@ -3,7 +3,9 @@
 // request time: an app that boots with /_x mounted in prod has already lost.
 
 // Type-only, so it is erased and the 46-component barrel stays out of the mount graph — the
-// values arrive through the dynamic `import()` in `shellStyle()`, same reason as `data.ts`.
+// values arrive through the dynamic `import()` in `devShellStyle()`, same reason as `data.ts`.
+import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { t } from '@ultimat3/i18n';
 import type { ColorRole } from '@ultimat3/ui';
 import { DevDashboardInProdError } from '../errors';
 import { defaultDevSources } from './data';
@@ -36,7 +38,7 @@ export const DEV_BASE_PATH = '/_x';
 export interface DevDashboardOptions {
   /** `ROLE` for this process. Defaults to `process.env.ROLE`. */
   readonly role?: string;
-  /** `NODE_ENV` (or `X_ENV`). Defaults to the environment. */
+  /** An explicit environment name. Defaults to `ULTIMATE_ENV`, else `NODE_ENV`, else development. */
   readonly env?: string;
   readonly basePath?: string;
   readonly sources?: DevSources;
@@ -49,15 +51,20 @@ const envOf = (name: string): string | undefined => {
 };
 
 /**
- * One rule: anything that says "production" refuses. Checked against both the framework's
- * `ROLE`-adjacent env and `NODE_ENV`, since a container may set only one of them.
+ * One rule: anything that says "production" refuses. The environment has ONE reader —
+ * `tryResolveEnvironment()`, which is `ULTIMATE_ENV` else `NODE_ENV` — because this guard used to
+ * read `X_ENV`/`NODE_ENV` and never the framework's own key, so an app declaring production the
+ * documented way mounted /_x on the internet. Non-throwing: a malformed `ULTIMATE_ENV` is its own
+ * error with its own fix and must not be raised for the first time by a mount guard.
+ * The `role` half survives only for an explicit `devDashboard({ role })` — no shipped `ROLE`
+ * value is `production`.
  */
 export function assertDevOnly(input: {
   role?: string | undefined;
   env?: string | undefined;
 }): void {
   const role = input.role ?? envOf('ROLE') ?? 'dev';
-  const env = input.env ?? envOf('X_ENV') ?? envOf('NODE_ENV') ?? 'development';
+  const env = input.env ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
   if (env === 'production' || env === 'prod' || role === 'production' || role === 'prod') {
     throw new DevDashboardInProdError({ role, env });
   }
@@ -113,8 +120,12 @@ let stylePromise: Promise<string> | undefined;
  * here went stale through a WCAG retune and shipped `line` on `surface-raised` at 1.16:1.
  * Reached by dynamic `import()` for the same reason `data.ts` is: /_x stays out of the
  * production graph, and the 46-component barrel loads only once a panel is actually drawn.
+ *
+ * Exported because the host that mounts /_x is the one that configures the CSP the panels are
+ * served under, and the `style-src` hash it needs is of THIS text — a host that hashed its own
+ * copy would send a policy that blocks the document this function actually writes.
  */
-async function shellStyle(): Promise<string> {
+export async function devShellStyle(): Promise<string> {
   stylePromise ??= import('@ultimat3/ui').then(({ colorTokens }) => {
     const block = (theme: 'light' | 'dark'): string =>
       SHELL_ROLES.map((role) => `--x-color-${role}: ${colorTokens[theme][role]};`).join(' ');
@@ -138,7 +149,7 @@ function shell(
   const tabs = panels
     .map(
       (panel) =>
-        `<a href="${basePath}/${panel.key}"${panel.key === active.key ? ' aria-current="page"' : ''}>${panel.key}</a>`,
+        `<a href="${basePath}/${panel.key}"${panel.key === active.key ? ' aria-current="page"' : ''}>${escapeHtml(t(panel.titleKey))}</a>`,
     )
     .join(' ');
 
@@ -149,7 +160,7 @@ function shell(
 <title>_x · ${escapeHtml(active.key)}</title><style>${style}</style></head>
 <body><header><h1>_x</h1><nav>${tabs}</nav>
 <a href="${basePath}/${active.key}?json=1">--json</a></header>
-<main><p class="question">${escapeHtml(active.question)}</p>
+<main><p class="question">${escapeHtml(t(active.questionKey))}</p>
 <pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre></main></body></html>`;
 }
 
@@ -171,7 +182,7 @@ export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
         error: {
           code: 'X_ADMIN_ENTITY_UNKNOWN',
           cause: `no /_x panel named "${key}" (have: ${[...byKey.keys()].join(', ')})`,
-          fix: `x dev --panel ${[...byKey.keys()][0] ?? 'routes'}`,
+          fix: `x dev   # then the ${[...byKey.keys()][0] ?? 'routes'} panel at /_x`,
         },
       };
     }
@@ -198,7 +209,7 @@ export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
 
       return wantsJson
         ? jsonResponse(payload, payload.ok ? 200 : 500)
-        : new Response(shell(await shellStyle(), basePath, panels, panel, payload), {
+        : new Response(shell(await devShellStyle(), basePath, panels, panel, payload), {
             status: 200,
             headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
           });

package/src/errors.ts

@@ -16,6 +16,11 @@ export const ADMIN_OWNED_ERROR_CODES = [
   'X_ADMIN_DENIED',
   'X_ADMIN_TOOL_FORBIDDEN',
   'X_ADMIN_INVALID',
+  // The two ways a `pages:` entry can be wrong. Both are thrown by `defineAdmin` at declaration,
+  // not on the first request: an admin page that is public, or one that shadows a generated
+  // screen, is a defect the author must never be able to deploy.
+  'X_ADMIN_PAGE_UNGUARDED',
+  'X_ADMIN_PAGE_PATH_INVALID',
 ] as const;
 
 /**
@@ -41,6 +46,8 @@ export const ADMIN_ERROR_TITLES: Readonly<Record<AdminOwnedErrorCode, string>> =
   X_ADMIN_DENIED: 'the actor may not use this admin surface',
   X_ADMIN_TOOL_FORBIDDEN: 'an admin MCP tool was called without permission',
   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',
 };
 
 // One unconditional call, so a second package claiming one of admin's codes throws
@@ -83,18 +90,54 @@ export class AdminFieldUnsupportedError extends UltimateError {
   }
 }
 
-/** An action reached the admin without a policy — the button would be an open door. */
+/**
+ * An action reached the admin without a policy — the button would be an open door.
+ *
+ * The subject's NAME goes in the cause and the permission's SHAPE goes in the fix: `can()` takes
+ * `resource:verb` (`Permission` is `` `${string}:${string}` ``), and `subject` is an export name,
+ * so the `can('<the action name>')` this used to emit was a paste that could not compile. No
+ * `allow()` branch, unlike action's and query's twin: an unguarded admin operation is the one
+ * thing this code exists to refuse.
+ */
 export class AdminPolicyMissingError extends UltimateError {
   constructor(input: { subject: string; kind: 'action' | 'resource' }) {
     super({
       code: 'X_ADMIN_POLICY_MISSING',
       cause: `${input.kind} "${input.subject}" is exposed in the admin with no policy`,
-      fix: `add policy: can('${input.subject}') to the ${input.kind} definition`,
+      fix: `add \`policy: can('<resource>:<verb>')\` to the ${input.kind} "${input.subject}" — a permission your definePermissions() call declares, never the ${input.kind}'s own name`,
       docs: docsFor('X_ADMIN_POLICY_MISSING'),
     });
   }
 }
 
+/**
+ * A `pages:` entry with an empty permission list. Refused where it is written, because the
+ * alternative is an unauthenticated admin screen that `x verify` is perfectly happy with — the
+ * route table would carry `permissions: []` and the emitted `defineRoute` would have no policy.
+ */
+export class AdminPageUnguardedError extends UltimateError {
+  constructor(input: { path: string }) {
+    super({
+      code: 'X_ADMIN_PAGE_UNGUARDED',
+      cause: `the admin page "${input.path}" declares no permissions, so nothing gates it`,
+      fix: `add permissions: ['${input.path.replace(/^\//, '').split('/')[0] ?? 'ops'}:read'] to the pages entry for "${input.path}"`,
+      docs: docsFor('X_ADMIN_PAGE_UNGUARDED'),
+    });
+  }
+}
+
+/** A page path that cannot be mounted: not rooted, malformed, or already served. */
+export class AdminPagePathInvalidError extends UltimateError {
+  constructor(input: { path: string; cause: string; fix: string }) {
+    super({
+      code: 'X_ADMIN_PAGE_PATH_INVALID',
+      cause: `the admin page path "${input.path}" ${input.cause}`,
+      fix: input.fix,
+      docs: docsFor('X_ADMIN_PAGE_PATH_INVALID'),
+    });
+  }
+}
+
 /**
  * A `/_x` panel needs a fact the framework cannot introspect on its own — request traces,
  * caught mail, the read-only SQL tool, the committed manifest. Thrown instead of drawing an

package/src/fields.ts

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

package/src/index.ts

@@ -91,6 +91,8 @@ export {
   type AdminErrorCode,
   type AdminErrorParts,
   AdminFieldUnsupportedError,
+  AdminPagePathInvalidError,
+  AdminPageUnguardedError,
   AdminPolicyMissingError,
   adminErrorFrom,
   DevDashboardInProdError,
@@ -127,6 +129,15 @@ export {
   adminToolDecisions,
 } from './mcp-tools';
 export { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
+export { AdminPageDenied, guardedPage } from './page-guard';
+export {
+  type AdminCustomPage,
+  type AdminPageComponent,
+  type AdminPageProps,
+  pageNavItems,
+  pagePermissions,
+  pageRoutes,
+} from './pages';
 export {
   type AdminCursor,
   type AdminPage,
@@ -186,7 +197,12 @@ export {
   repoOf,
   resourceFor,
 } from './resource';
-export { type AdminRouteConfig, adminRouteConfig, adminRoutes } from './routes';
+export {
+  type AdminRouteConfig,
+  adminRouteConfig,
+  adminRouteFor,
+  adminRoutes,
+} from './routes';
 export {
   type AdminSearchHit,
   type AdminSearchInput,