@ultimat3/admin 30.9.0 → 31.1.0

package/CLAUDE.md

@@ -46,7 +46,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **An edit is optimistic** (`row-version.ts`): the form posts `_version` = `rowVersion(row)` (keyed), `adminUpdate(…, { version })` answers `stale` — 409, `admin.error.row-changed`, the form re-drawn over the row as it is now — when the row moved on; a post with no version is stale. An instant posted back as it was drawn (`datetimeInputValue`) is LEFT OUT of the patch (`decodeForm(…, before)`): `datetime-local` holds minutes. A create or update is decided again on the validated values as `subject.input` (update: beside `row`).
 - **The audit trail is the actor's tenant's**: `/admin/audit` and the history card pass `orgId` to `entries()` when the actor has one (`audit-tenancy.test.ts`).
 - **A table read by a runtime key is `Object.hasOwn` / a `Map`, never a bare index** — `impliedBy`, the `/_x` counters, `list-filters.ts`' operator table, `renderers.tsx` (`bun run proto-index`).
-- **The `/_x` SQL runs in `readOnlyQuery`** (`dev/sql-runner.ts`, `readOnlySql(client)` — what a host wires as `runSql`): read-only transaction, timeout, `DEV_SQL_MAX_ROWS`.
+- **The `/_x` SQL runs in `readOnlyQuery`** (`dev/sql-runner.ts`, `readOnlySql(client)`, a host's `runSql`): read-only txn, timeout, `DEV_SQL_MAX_ROWS`, SELECT-only role.
 - **One read-only SQL guard, and it is `@ultimat3/mcp`'s** — no local keyword scan; the panel keeps only the emptiness test and the way out (`psql "$DATABASE_URL"`, the developer's own client — `x db` has no `psql`).
 - **Every admin operation is audited, reads included**, not `/admin`'s counts (a count reads no row). `ListResult` carries its `AuditEntry` on both branches (`entityId: null`); `AdminSearchResult.audit` one entry per resource decided, and a skipped resource (no text field, no repo, a repo that threw) is in `skipped`, never a 500.
 - **A write's RESULT satisfies the actor's row scope** (`row-scope-write.ts`): a create, and an update over the fields it touches, outside `rows(actor)` is refused before the repo — `admin.error.row-out-of-scope`, audited as a denial. The one predicate evaluator in this package; an ordering over text is refused, never guessed. `row-scope-write.test.ts`.
@@ -109,6 +109,6 @@ From the repo root — the seal-key preload is the root's, so `bun test --filter
 directory fails on the first sealed column:
 
 ```bash
-bun test packages/admin
+bun test ./packages/admin/
 bunx tsc --noEmit -p packages/admin/tsconfig.json
 ```

package/README.md

@@ -32,7 +32,7 @@ One panel per file. Each kills one question, and each is available as `--json`
 | `timeline` | where did the time go? — a server-rendered waterfall of SQL, cache, action, policy spans (one row per span, bar placed by the payload's own `offset`/`width`), time per kind, and the N+1 detector's verdicts with their fix lines; the payload folded under it |
 | `live` | what does each subscriber receive, and **why** — the matcher's decision trace |
 | `jobs` | a ring of the recent runs by state (`DonutChart`), then the admin's own jobs overview (`/admin/jobs`'s component) over this process's queue; the payload — queue depth, step traces, retry-from-step target, dead letter — folded under it |
-| `db` | psql in a tab (read-only twice: `assertReadOnly` refuses DML, and `readOnlySql(client)` — what a host wires as `runSql` — runs it in a `BEGIN READ ONLY` transaction with a timeout and `DEV_SQL_MAX_ROWS`), schema + drift (`null` unless a host wires the check) |
+| `db` | psql in a tab (read-only twice: `assertReadOnly` refuses DML, and `readOnlySql(client)` — what a host wires as `runSql` — runs it in a `BEGIN READ ONLY` transaction with a timeout, `DEV_SQL_MAX_ROWS` and the SELECT-only role `ensureReadOnlyRole` grants), schema + drift (`null` unless a host wires the check) |
 | `mail` | caught mail, rendered, per locale, with the locale gaps listed; beside it every declared mail's `preview` rendered per locale (`mailTemplates`, the host's source: `x dev` wires it) |
 | `cache` | the tag graph — what invalidated what, and which tags are orphans |
 | `policy` | the permission matrix per actor, every cell carrying its trace |
@@ -330,9 +330,9 @@ import { AdminList, listHref, Widget } from '@ultimat3/admin';
 <Widget field={field} value={row.total} ctx={ctx} mode="read" />;
 ```
 
-`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.
+`Widget` takes the field and the raw row value, not pre-derived props: the internal
+`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.
 
 ### Mounting it yourself
 
@@ -522,6 +522,8 @@ Opt-in AI panes, each declaring the scope it needs (`aiPanes({ enable: ['anomaly
 | `backlog-forecast` | `jobs:read`, `metrics:read` |
 
 Panes are off until enabled, and `runAiPane` refuses (never no-ops) without a runner.
+`GatewayAdapter` — the type a host narrows `@ultimat3/ai`'s `Gateway` to an `AiRunner` with — is
+`@ultimat3/admin/adapter`'s, off the barrel.
 
 ## Errors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "30.9.0",
+  "version": "31.1.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -25,6 +25,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
     "./dev": "./src/dev/index.ts",
     "./schema": "./src/audit-schema.ts",
     "./error-groups": "./src/error-groups.ts"
@@ -45,21 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.9.0",
-    "@ultimat3/ai": "30.9.0",
-    "@ultimat3/cache": "30.9.0",
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/db": "30.9.0",
-    "@ultimat3/entity": "30.9.0",
-    "@ultimat3/http": "30.9.0",
-    "@ultimat3/i18n": "30.9.0",
-    "@ultimat3/jobs": "30.9.0",
-    "@ultimat3/mcp": "30.9.0",
-    "@ultimat3/money": "30.9.0",
-    "@ultimat3/policy": "30.9.0",
-    "@ultimat3/query": "30.9.0",
-    "@ultimat3/render": "30.9.0",
-    "@ultimat3/schema": "30.9.0",
-    "@ultimat3/ui": "30.9.0"
+    "@ultimat3/action": "31.1.0",
+    "@ultimat3/ai": "31.1.0",
+    "@ultimat3/cache": "31.1.0",
+    "@ultimat3/core": "31.1.0",
+    "@ultimat3/db": "31.1.0",
+    "@ultimat3/entity": "31.1.0",
+    "@ultimat3/http": "31.1.0",
+    "@ultimat3/i18n": "31.1.0",
+    "@ultimat3/jobs": "31.1.0",
+    "@ultimat3/mcp": "31.1.0",
+    "@ultimat3/money": "31.1.0",
+    "@ultimat3/policy": "31.1.0",
+    "@ultimat3/query": "31.1.0",
+    "@ultimat3/render": "31.1.0",
+    "@ultimat3/schema": "31.1.0",
+    "@ultimat3/ui": "31.1.0"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,5 @@
+// `@ultimat3/admin/adapter` — what a host wiring an AI gateway into the admin reads: the shape of
+// the function that narrows `@ultimat3/ai`'s `Gateway` to the runner a pane may call. Never the
+// `.` barrel: an app declares an admin; only the code that hands it a gateway needs this.
+
+export type { GatewayAdapter } from './ai-panes';

package/src/admin.ts

@@ -105,6 +105,11 @@ export interface DefineAdminInput {
 
 export interface AdminApp {
   readonly basePath: string;
+  /**
+   * Where "back to the app" goes: `/` as declared; the root a request was served under behind an
+   * HTTP base path or a routed locale (`/myapp/es/`) — `adminAppFor`, `localized-app.ts`.
+   */
+  readonly home?: string;
   readonly branding: AdminBranding;
   readonly theme: ThemeAttributes;
   readonly resources: readonly AdminResource[];
@@ -414,6 +419,7 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
 
   const app: AdminApp = {
     basePath,
+    home: '/',
     branding,
     theme: themeAttributes(branding),
     resources,

package/src/audit-pg.ts

@@ -3,6 +3,7 @@
 // every restart, and a row's history that ends at the last deploy is not a history.
 
 import { isUltimateError, uuidV7 } from '@ultimat3/core';
+import type { AuditSink } from '@ultimat3/core/adapter';
 import { type DbClient, db, withTransaction } from '@ultimat3/db';
 import {
   AUDIT_READ_OPERATIONS,
@@ -12,7 +13,6 @@ import {
   type AuditLog,
   type AuditOutcome,
   type AuditQuery,
-  type AuditSink,
   auditEntry,
   auditLimit,
   auditWindow,
@@ -138,7 +138,7 @@ export interface PostgresAuditLogOptions {
    * read is an event and is always written.
    */
   readonly reads?: boolean;
-  readonly sinks?: readonly AuditSink[];
+  readonly sinks?: readonly AuditSink<AuditEntry>[];
   readonly now?: () => Date;
   /** Must answer a uuid: the column is one. Omitted, a time-ordered v7. */
   readonly nextId?: () => string;

package/src/audit.ts

@@ -3,6 +3,7 @@
 // there is deliberately no update or delete on this interface.
 
 import { canonicalJson, finiteCount, REDACTED } from '@ultimat3/core';
+import type { AuditSink } from '@ultimat3/core/adapter';
 import type { AdminActor, AdminDecision } from './authz';
 import { AdminFilterInvalidError } from './errors';
 import { instantOf } from './list-filters';
@@ -55,11 +56,6 @@ export interface AuditDraft {
   readonly diff?: readonly AuditFieldDiff[];
 }
 
-/** Where a copy of every entry goes besides the log's own store: stdout as JSON lines, OTel. */
-export interface AuditSink {
-  write(entry: AuditEntry): Promise<void> | void;
-}
-
 /** A position in the trail: the entry a page ended on. Entries are ordered `at` then `id`. */
 export interface AuditCursor {
   readonly at: string;
@@ -113,7 +109,11 @@ export interface AuditLog {
 }
 
 export interface AuditLogOptions {
-  readonly sinks?: readonly AuditSink[];
+  /**
+   * Where a copy of every entry goes besides the log's own store: stdout as JSON lines, OTel.
+   * `@ultimat3/core`'s one `AuditSink`, over this package's entry — there is no second interface.
+   */
+  readonly sinks?: readonly AuditSink<AuditEntry>[];
   /** Injected so tests get deterministic timestamps and ids. */
   readonly now?: () => Date;
   readonly nextId?: () => string;

package/src/dev/panel-timeline.ts

@@ -39,23 +39,39 @@ export interface TimelinePanelData {
   readonly nPlusOne: readonly StatementLoopFact[] | null;
 }
 
+/**
+ * Depth-first by start time. A span whose parent is not in this recording — work handed off after
+ * its trace's early spans were evicted, or a host's own parenting — is drawn at depth 0, as is one
+ * caught in a parent cycle: `totalsByKind` counts every span, so the flame must draw every span,
+ * and a walk from `null` alone left those out of it without a word.
+ */
 function flatten(trace: RequestTrace): readonly FlameRow[] {
+  const ids = new Set(trace.spans.map((span) => span.id));
   const byParent = new Map<string | null, TimelineSpan[]>();
   for (const span of trace.spans) {
-    const bucket = byParent.get(span.parentId) ?? [];
+    const parent =
+      span.parentId !== null && span.parentId !== span.id && ids.has(span.parentId)
+        ? span.parentId
+        : null;
+    const bucket = byParent.get(parent) ?? [];
     bucket.push(span);
-    byParent.set(span.parentId, bucket);
+    byParent.set(parent, bucket);
   }
   const total = trace.totalMs === 0 ? 1 : trace.totalMs;
   const rows: FlameRow[] = [];
+  const drawn = new Set<TimelineSpan>();
+  const byStart = (spans: readonly TimelineSpan[]) =>
+    [...spans].sort((a, b) => a.startMs - b.startMs);
 
-  const walk = (parentId: string | null, depth: number): void => {
-    for (const span of (byParent.get(parentId) ?? []).sort((a, b) => a.startMs - b.startMs)) {
-      rows.push({ span, depth, offset: span.startMs / total, width: span.durationMs / total });
-      walk(span.id, depth + 1);
-    }
+  const draw = (span: TimelineSpan, depth: number): void => {
+    if (drawn.has(span)) return;
+    drawn.add(span);
+    rows.push({ span, depth, offset: span.startMs / total, width: span.durationMs / total });
+    for (const child of byStart(byParent.get(span.id) ?? [])) draw(child, depth + 1);
   };
-  walk(null, 0);
+  for (const span of byStart(byParent.get(null) ?? [])) draw(span, 0);
+  // Only a cycle of two or more spans is left: none of them is anyone's root.
+  for (const span of byStart(trace.spans)) draw(span, 0);
   return rows;
 }
 

package/src/dev/sql-runner.ts

@@ -1,8 +1,9 @@
 // The `/_x` DB panel's statement, RUN: inside `readOnlyQuery` — its own `BEGIN READ ONLY`
-// transaction, a statement timeout and a row ceiling — never through the app's plain `db.query`.
-// A host wires `runSql: readOnlySql(client)`; the guard upstream decides what reaches it.
+// transaction, a statement timeout, a row ceiling and the SELECT-only role — never through the
+// app's plain `db.query`. A host wires `runSql: readOnlySql(client)`; the guard upstream decides
+// what reaches it.
 
-import { type DbClient, readOnlyQuery } from '@ultimat3/db';
+import { type DbClient, ensureReadOnlyRole, readOnlyQuery } from '@ultimat3/db';
 import type { SqlResult } from './facts';
 
 /**
@@ -14,15 +15,30 @@ export const DEV_SQL_MAX_ROWS = 500;
 /**
  * The runner a `/_x` host hands the DB panel. `assertReadOnlyQuery` (`panel-db.ts`) is the parse
  * guard; this is the SERVER saying no: a statement the guard let through that writes, locks or
- * runs away still meets a read-only transaction that always rolls back, with the app's own
- * credentials and no way to commit. Columns are the first row's keys — the driver hands objects.
+ * runs away still meets a read-only transaction that always rolls back, run as the role
+ * `ensureReadOnlyRole` grants SELECT and nothing else — the layer MCP's `db.query` already had.
+ * The app's own credentials are often a dev superuser, so without it a parse-guard miss met one
+ * layer, not two. Columns are the first row's keys — the driver hands objects.
+ *
+ * The role's DDL runs until it succeeds, then never again for this runner. `ensureReadOnlyRole`
+ * never throws: a database that refuses `CREATE ROLE` answers `null`, the read runs without that
+ * layer, and the next statement asks again.
  */
 export function readOnlySql(client: DbClient): (sql: string) => Promise<SqlResult> {
+  let role: Promise<string | null> | undefined;
   return async (sql) => {
+    role ??= ensureReadOnlyRole(client);
+    const assumed = await role;
+    // `null` is not an answer to keep: a lost race (`x mcp serve` creating the role at the same
+    // moment) reads exactly like a refusal, and caching it ran every later statement without the
+    // layer. Asked again on the next statement; a role that exists is kept.
+    if (assumed === null) role = undefined;
+    // After the role: the panel times the statement, not the first call's one-off DDL.
     const started = performance.now();
     const { rows } = await readOnlyQuery<Readonly<Record<string, unknown>>>(sql, {
       client,
       maxRows: DEV_SQL_MAX_ROWS,
+      role: assumed,
     });
     const elapsedMs = Math.round(performance.now() - started);
     const columns = Object.keys(rows[0] ?? {});

package/src/error-groups-sink.ts

@@ -7,6 +7,7 @@ import {
   errorFingerprint,
   finiteCount,
   isRedactedKey,
+  localErrorSink,
   logger,
   REDACTED,
   renderThrowable,
@@ -158,7 +159,9 @@ export function errorGroupsSink(options: ErrorGroupsSinkOptions): ErrorGroupsSin
     }
   };
 
-  return {
+  // Local: the groups live in this app's own table, so a boot with `SENTRY_DSN` still adds its
+  // transport beside this sink rather than reading it as the app's monitor.
+  return localErrorSink({
     report(report: ErrorReport): void {
       try {
         if (options.ignore?.(report) === true) return;
@@ -177,5 +180,5 @@ export function errorGroupsSink(options: ErrorGroupsSinkOptions): ErrorGroupsSin
     async settled(): Promise<void> {
       while (pending.size > 0) await Promise.all([...pending]);
     },
-  };
+  });
 }

package/src/error-groups-store.ts

@@ -113,6 +113,7 @@ export function memoryErrorGroupsStore(): ErrorGroupsStore {
         ...seen,
         message: occurrence.message,
         status: statusAfterOccurrence(seen.status),
+        // biome-ignore lint/complexity/useMathMinMax: ISO-8601 STRINGS, compared as text — Math.max would return NaN.
         lastSeen: at > seen.lastSeen ? at : seen.lastSeen,
         count: seen.count + occurrence.count,
         sample: occurrence.sample,

package/src/index.ts

@@ -2,13 +2,10 @@
 // Explicit exports only — a barrel that re-exports everything is how internal helpers become
 // someone's dependency.
 
-export { AdminActionForm, type AdminActionFormProps } from './action-form';
 export {
-  ACTION_NOT_APPLICABLE_REASON,
   type ActionGateInput,
   type AdminActionButton,
   actionButtons,
-  actionDecisions,
   adminPermissionForAction,
   decideAction,
   type InvokeInput,
@@ -16,30 +13,9 @@ export {
   invokeAdminAction,
   permissionsForAction,
 } from './action-gate';
-export {
-  ACTION_INPUT_PREFIX,
-  type ActionInputControl,
-  type ActionInputField,
-  actionInputFields,
-  decodeActionInput,
-} from './action-input';
 export { invokeRowAction, type RowActionInput } from './action-row';
-export {
-  ACTION_OPERATION,
-  ACTION_PARAM,
-  AdminActions,
-  type AdminActionsProps,
-  actionFormHref,
-  BATCH_OPERATION,
-  DELETE_OPERATION,
-  OPERATION_FIELD,
-} from './actions';
-export {
-  type AdminRequestActor,
-  ANONYMOUS_ADMIN_ACTOR,
-  adminActorFrom,
-  requestActor,
-} from './actor';
+export { AdminActions, type AdminActionsProps } from './actions';
+export { adminActorFrom } from './actor';
 export {
   type AdminApp,
   type AdminAuth,
@@ -58,12 +34,9 @@ export {
   type AiPanesOptions,
   type AiRunner,
   aiPanes,
-  type GatewayAdapter,
   runAiPane,
 } from './ai-panes';
 export {
-  AUDIT_PAGE_DEFAULT,
-  AUDIT_PAGE_MAX,
   type AuditCursor,
   type AuditDraft,
   type AuditEntry,
@@ -72,25 +45,15 @@ export {
   type AuditLogOptions,
   type AuditOutcome,
   type AuditQuery,
-  type AuditSink,
   auditCursorOf,
-  auditEntry,
   auditEntryMatches,
   auditWindow,
   deniedDraft,
   diffRows,
   memoryAuditLog,
 } from './audit';
-export {
-  type PostgresAuditLogOptions,
-  postgresAuditLog,
-} from './audit-pg';
-export {
-  type AuditRequest,
-  auditHref,
-  auditRequestOf,
-  HISTORY_PARAM,
-} from './audit-request';
+export { type PostgresAuditLogOptions, postgresAuditLog } from './audit-pg';
+export { type AuditRequest, auditHref, auditRequestOf, HISTORY_PARAM } from './audit-request';
 // The audit table's DDL is `@ultimat3/admin/schema`'s alone — one import path for one statement.
 export {
   type AdminActor,
@@ -100,36 +63,23 @@ export {
   type AdminSubject,
   adminAllowed,
   adminDenied,
-  anonymousAuthz,
   decideAll,
   expandPermissions,
-  isAllowed,
   staticAuthz,
 } from './authz';
 export {
   type AdminBatchAnswer,
   type AdminBatchInput,
   type AdminBatchResult,
-  BATCH_NOT_OFFERED_REASON,
   type BatchEnqueue,
   type BatchRow,
   type BatchRowOutcome,
   type BatchSelection,
-  batchConfirmationToken,
   batchPlan,
   MAX_BATCH_QUEUED_ROWS,
   MAX_BATCH_ROWS,
   runAdminBatch,
 } from './batch';
-export {
-  AdminBatchBar,
-  type AdminBatchBarProps,
-} from './batch-bar';
-export {
-  ADMIN_BATCH_JOB,
-  batchEnqueue,
-} from './batch-job';
-export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
 export { BATCH_QUEUED_REASON } from './batch-queue';
 export {
   type AdminClaimData,
@@ -151,37 +101,26 @@ export {
   type ListResult,
   permissionsForOperation,
 } from './crud';
-export {
-  type AdminActionDescription,
-  type AdminDescription,
-  type AdminResourceDescription,
-  type AdminRouteDescription,
-  type AdminScopeDescription,
-  type AdminSectionDescription,
-  describeAdmin,
+export type {
+  AdminActionDescription,
+  AdminDescription,
+  AdminResourceDescription,
+  AdminRouteDescription,
+  AdminScopeDescription,
+  AdminSectionDescription,
 } from './describe';
-export {
-  AdminDetail,
-  type AdminDetailProps,
-} from './detail';
-export {
-  type AdminColumnFacts,
-  type AdminColumnReference,
-  adminColumnsOf,
-  adminSealedColumnsOf,
-} from './entity-columns';
+export { AdminDetail, type AdminDetailProps } from './detail';
+export type { AdminColumnFacts, AdminColumnReference } from './entity-columns';
 // The screens only. The sink and its stores are `@ultimat3/admin/error-groups`'s alone: every role
 // installs the sink, and this barrel would carry every admin screen into a worker's graph.
 export { ERRORS_READ, type ErrorGroupsPagesOptions, errorGroupsPages } from './error-groups-pages';
+export type { AdminErrorCode } from './errors';
 // The /_x dashboard is NOT re-exported here — it has its own door, `@ultimat3/admin/dev`, so a
 // host that only mounts the dev panels never loads a production admin component.
 export {
-  ADMIN_ERROR_CODES,
-  ADMIN_ERROR_TITLES,
   AdminActionDuplicateError,
   AdminActionNotApplicableError,
   AdminEntityUnknownError,
-  type AdminErrorCode,
   type AdminErrorParts,
   AdminFieldUnsupportedError,
   AdminFilterInvalidError,
@@ -190,7 +129,6 @@ export {
   AdminPageUnguardedError,
   AdminPolicyMissingError,
   AdminRepoUnboundError,
-  adminErrorFrom,
   DevDashboardInProdError,
   DevSourceUnavailableError,
 } from './errors';
@@ -199,51 +137,19 @@ export {
   type AdminFieldType,
   type AdminFilterKind,
   type AdminWidget,
-  fieldTypeFromColumn,
   filterable,
-  filterKindFor,
   listable,
   searchable,
   sortable,
-  WIDGET_BY_FIELD_TYPE,
-  widgetFor,
 } from './fields';
-export { AdminForm, type AdminFormProps, issueText } from './form';
-export { currencyFieldOf, decodeForm, posted } from './form-decode';
+export { AdminForm, type AdminFormProps } from './form';
+export { posted } from './form-decode';
 export { JOB_MANAGE, JOB_READ } from './jobs/job-actions';
-export { JOB_ENTITY } from './jobs/job-entities';
-export { JOBS_PATH, jobRowScope } from './jobs/job-resources';
+export { jobRowScope } from './jobs/job-resources';
 export { AdminLayout, type AdminLayoutProps, adminActorLabel } from './layout';
 export { AdminList, type AdminListProps } from './list';
-export { type ResourceColumnsInput, resourceColumns } from './list-columns';
-export { AdminFilterBar, type AdminFilterBarProps } from './list-filter-bar';
-export {
-  type AskedFilter,
-  checkedFilter,
-  declaredFilters,
-  FILTER_PREFIX,
-  filterOpsOf,
-  filterParam,
-  knownFilterParams,
-} from './list-filters';
-export {
-  CURSOR_PARAM,
-  type ListLocation,
-  listHref,
-  pageRequestOf,
-  SCOPE_PARAM,
-  SORT_PARAM,
-} from './list-request';
-export {
-  type AdminListRequest,
-  findRow,
-  type ListWhere,
-  listWhere,
-  rowWhere,
-  scopeCounts,
-  scopeNamed,
-} from './list-scope';
-export { AdminScopeTabs, type AdminScopeTabsProps } from './list-scope-tabs';
+export { type ListLocation, listHref, pageRequestOf } from './list-request';
+export { type AdminListRequest, findRow, type ListWhere, listWhere } from './list-scope';
 export { type AdminMcpActor, type AdminMcpOptions, adminMcp } from './mcp';
 export { type AdminToolResult, callAdminTool, type McpInput } from './mcp-dispatch';
 export { adminTokenScopes, adminToolScopes } from './mcp-scopes';
@@ -253,40 +159,21 @@ export {
   type AdminToolKind,
   adminMcpTools,
   adminToolCatalog,
-  adminToolDecisions,
 } from './mcp-tools';
-export {
-  ADMIN_MOUNTS,
-  adminMountAt,
-  adminMounts,
-  clearAdminMounts,
-  registerAdminMount,
-} from './mounts';
-export { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
-export { AdminPageDenied, auditRefusal } from './page-guard';
+export { ADMIN_MOUNTS, adminMounts, clearAdminMounts } from './mounts';
+export { type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
+export { AdminPageDenied } from './page-guard';
 export {
   type AdminCustomPage,
   type AdminPageComponent,
   type AdminPageProps,
-  pageNavItems,
   pagePermissions,
   pageRoutes,
 } from './pages';
-export {
-  type AdminCursor,
-  type AdminPage,
-  decodeAdminCursor,
-  encodeAdminCursor,
-  fetchPage,
-  listQuery,
-  type PageRequest,
-  pageFrom,
-} from './pagination';
+export { type AdminCursor, type AdminPage, type PageRequest, pageFrom } from './pagination';
 export {
   ADMIN_DESTROY,
-  ADMIN_IMPERSONATE,
   ADMIN_OPERATION_RULES,
-  ADMIN_OPERATIONS,
   ADMIN_PERMISSION_SPEC,
   ADMIN_PERMISSIONS,
   ADMIN_READ,
@@ -294,8 +181,6 @@ export {
   type AdminOperation,
   type AdminPermission,
   type AdminPermissionRule,
-  adminPermissionFor,
-  CONFIRMATION_REQUIRED_REASON,
   confirmationToken,
   entityPermissionFor,
   isDestructive,
@@ -327,64 +212,38 @@ export {
   type AdminSort,
   type AdminTable,
   type AdminTableRead,
-  computedRow,
-  FILTER_OPS,
   type FilterOp,
   type KeysetBound,
-  type RegisteredEntity,
-  type RegisteredTable,
   readField,
   rowId,
 } from './registry';
+export { type AdminRelated, type AdminRelatedList, relatedLists, relatedOf } from './related';
 export {
-  type AdminRelated,
-  type AdminRelatedList,
-  RELATED_PAGE_SIZE,
-  relatedLists,
-  relatedOf,
-} from './related';
-export {
-  type AdminLookupRequest,
-  type AdminLookupResult,
   type AdminOption,
-  adminLookup,
-  LOOKUP_SELECT_MAX,
   labelOf,
   type RelationData,
   type RelationNeed,
   relationDataFor,
-  relationNeeds,
 } from './relations';
-export { ComputedCell, TRUNCATE_AT } from './renderers';
-export { adminEntitiesOf, adminRepoFor, adminTablesOf } from './repo-entity';
-export {
-  type AdminResource,
-  type AdminResourceOptions,
-  adminResource,
-  repoOf,
-  resourceFor,
-} from './resource';
+export { adminEntitiesOf, adminRepoFor } from './repo-entity';
+export { type AdminResource, type AdminResourceOptions, adminResource, repoOf } from './resource';
 export type { AdminFieldOverride } from './resource-fields';
-export {
-  type AdminFormGroupOptions,
-  type AdminSection,
-  type AdminSectionOptions,
-  DEFAULT_SECTION_KEY,
+export type {
+  AdminFormGroupOptions,
+  AdminSection,
+  AdminSectionOptions,
 } from './resource-layout';
-export {
-  ADMIN_RENDERERS,
-  type AdminColumnComponent,
-  type AdminColumnRenderProps,
-  type AdminComputedColumn,
-  type AdminComputedColumnOptions,
-  type AdminRenderer,
-  type AdminRowScope,
-  type AdminScope,
-  type AdminScopeOptions,
-  type AdminScopeWhere,
-  LOOKUP_SEGMENT,
+export type {
+  AdminColumnComponent,
+  AdminColumnRenderProps,
+  AdminComputedColumn,
+  AdminComputedColumnOptions,
+  AdminRenderer,
+  AdminRowScope,
+  AdminScope,
+  AdminScopeOptions,
+  AdminScopeWhere,
 } from './resource-list';
-export { AdminViewWriteError, VIEW_OPERATIONS } from './resource-operations';
 export {
   type AdminRouteConfig,
   type AdminRouteMatch,
@@ -393,17 +252,13 @@ export {
   adminRouteMatch,
   adminRoutes,
 } from './routes';
-export { ROW_OUT_OF_SCOPE_REASON } from './row-scope-write';
 export { ROW_CHANGED_REASON, rowVersion, VERSION_FIELD } from './row-version';
 export {
   type AdminRouteRequest,
   type AdminRouteResponse,
   type AdminScreen,
   guardedScreen,
-  lookupHref,
-  widgetContextOf,
 } from './screen-frame';
-export { type OperationDecision, OperationMatrix, operationMatrix } from './screen-home';
 export {
   type AdminSearchHit,
   type AdminSearchInput,
@@ -411,23 +266,12 @@ export {
   adminSearch,
 } from './search';
 export { type AdminTestCtxInput, adminTestCtx } from './test-ctx';
-export {
-  type AdminBranding,
-  adminBranding,
-  defaultBranding,
-  type ThemeAttributes,
-  type ThemeMode,
-  type ThemeTokenRef,
-  themeAttributes,
+export type {
+  AdminBranding,
+  ThemeAttributes,
+  ThemeMode,
+  ThemeTokenRef,
 } from './theme';
 export { type ValidationIssue, type ValidationResult, validateInput } from './validate';
-export {
-  assertMoney,
-  assertZone,
-  type GuardedField,
-  type SelectOption,
-  type WidgetContext,
-  type WidgetProps,
-  widgetProps,
-} from './widget-value';
+export type { SelectOption, WidgetContext, WidgetProps } from './widget-value';
 export { optionLabel, Widget, type WidgetInput } from './widgets';

package/src/jobs/operator.ts

@@ -21,13 +21,13 @@ export function jobsOperator(): JobsOperator {
     throw new DriverUnavailableError({
       driver: 'none',
       cause: 'the jobs dashboard was asked for rows and this process installed no queue',
-      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: setJobDriver(memoryJobDriver())',
+      fix: 'run the app through x dev or the container entry, which install the queue — or in a test: installJobDriver(memoryJobDriver()) from @ultimat3/jobs/adapter',
     });
   }
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg and memory drivers implement introspect',
+      fix: 'export const runtime = { jobs: postgresJobDriver() }   # apps/<app>/runtime.ts — or delete that line so the boot installs it; the pg and memory drivers implement introspect',
     });
   }
   return { driver, introspect: driver.introspect };

package/src/layout.tsx

@@ -128,7 +128,7 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
 
         {/* The way out. The admin's route table never points back at the app, so without this an
             operator who opened the dashboard has no link home and edits the URL bar. */}
-        <a class={styles['navLink']} href="/">
+        <a class={styles['navLink']} href={props.app.home ?? '/'}>
           {t('admin.backToApp')}
         </a>
       </aside>

package/src/localized-app.ts

@@ -0,0 +1,29 @@
+// The admin as one request reached it: the same declaration, its links rooted where the request
+// was SERVED — behind an HTTP base path, under a routed locale, or both (`/myapp/es/admin`). Every
+// link, form action and redirect a screen writes starts from `app.basePath` or `app.home`, so this
+// one substitution keeps every click where the operator is instead of dropping the prefix.
+
+import type { AdminApp } from './admin';
+
+/**
+ * `app` itself when it was reached at its declared base path; otherwise a copy whose `basePath` is
+ * the pathname up to and including the declared base (`/myapp/es/admin`) and whose `home` is the
+ * part before it with a trailing slash (`/myapp/es/`). The first match from the left is the mount:
+ * a row id or a page path that repeats the base comes after it. The route table (`routes`) is left
+ * as declared: the host matches on the stripped route path, and the audit names the route.
+ */
+export function adminAppFor(app: AdminApp, url: string): AdminApp {
+  const segments = (URL.parse(url, 'http://localhost')?.pathname ?? '').split('/').slice(1);
+  const base = app.basePath.split('/').filter((segment) => segment !== '');
+  for (let at = 0; at + base.length <= segments.length; at += 1) {
+    if (!base.every((segment, i) => segments[at + i] === segment)) continue;
+    if (at === 0) return app;
+    const served = segments.slice(0, at);
+    return {
+      ...app,
+      basePath: `/${[...served, ...base].join('/')}`,
+      home: `/${served.join('/')}/`,
+    };
+  }
+  return app;
+}

package/src/routes.ts

@@ -5,6 +5,7 @@
 import { compilePattern, type RouteConfig, type RouteGuard } from '@ultimat3/render';
 import type { AdminApp, AdminRoute } from './admin';
 import { AdminPagePathInvalidError } from './errors';
+import { adminAppFor } from './localized-app';
 import { adminRouteDefinition } from './route-config';
 import type { AdminRouteRequest, AdminRouteResponse } from './screen-frame';
 import { screenFor } from './screens';
@@ -32,12 +33,19 @@ export interface AdminRouteConfig {
 /** One route of the table, with its gate, its served config and its screen. */
 export function adminRouteConfig(app: AdminApp, route: AdminRoute): AdminRouteConfig {
   const { policy, config } = adminRouteDefinition(route);
+  // Built now, so a route with nothing behind it is refused at mount, not at its first request.
+  const screen = screenFor(app, route);
   return {
     path: route.path,
     view: route.view,
     entity: route.entity,
     permissions: route.permissions,
-    respond: screenFor(app, route),
+    // Under a routed locale the screen is built over the admin as that locale spells it, so every
+    // link and redirect keeps the prefix (`localized-app.ts`).
+    respond: (request) => {
+      const under = adminAppFor(app, request.url);
+      return (under === app ? screen : screenFor(under, route))(request);
+    },
     policy,
     config,
   };

package/src/screen-system.tsx

@@ -100,6 +100,9 @@ export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
     // Refused before anything is read: a parameter this screen does not answer is a 400 naming
     // what it does (`guardedScreen`), never the unfiltered trail.
     const asked = auditRequestOf(new URL(request.url));
+    // The trail's links and its filter form point at the page AS SERVED — under `/es/admin/audit`
+    // that keeps the locale, where the declared `route.path` dropped it on every click.
+    const here = new URL(request.url).pathname;
     // The actor's tenant's trail: `audit:read` held in org A is not a read of org B's operators,
     // their ids or what they touched. An actor with no org — the platform — reads every tenant's.
     // Never a parameter: the URL cannot name another tenant.
@@ -128,7 +131,7 @@ export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
     const { before: _page, ...filters } = asked;
     return (
       <Card>
-        <AuditFilter action={route.path} asked={asked} />
+        <AuditFilter action={here} asked={asked} />
         {entries.length === 0 ? (
           <p class="x-admin-empty">{t('admin.audit.empty')}</p>
         ) : (
@@ -139,7 +142,7 @@ export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
               return (
                 <li>
                   <code>{entry.at}</code>{' '}
-                  <a href={auditHref(route.path, { ...filters, actorId: entry.actor.id })}>
+                  <a href={auditHref(here, { ...filters, actorId: entry.actor.id })}>
                     {entry.actor.id}
                   </a>{' '}
                   <span>{operationLabel(entry)}</span>{' '}
@@ -158,9 +161,7 @@ export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
           </ol>
         )}
         {last === null ? null : (
-          <Link href={auditHref(route.path, { ...filters, before: last })}>
-            {t('admin.audit.older')}
-          </Link>
+          <Link href={auditHref(here, { ...filters, before: last })}>{t('admin.audit.older')}</Link>
         )}
       </Card>
     );