@ultimat3/admin 30.8.0 → 31.0.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`.
@@ -95,7 +95,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `batch.ts` / `batch-queue.ts` / `batch-bar.tsx` / `batch-job.ts` | a batch through the gate / its queued half / the bar and row checkboxes / the `admin.batch` job |
 | `resource-fields.ts` / `resource-layout.ts` / `related.ts` / `list-columns.tsx` | one column → one field / sections and form groups / related lists / a resource's table columns |
 | `audit.ts` / `audit-pg.ts` / `json-text.ts` / `audit-request.ts` | the log interface + memory log / the Postgres log / readable JSON for a cell or a diff / the trail's URL ⇄ `AuditRequest`, the history cursor |
-| `mcp-tools.ts` / `mcp-scopes.ts` / `mcp.ts` | tool derivation, each tool's scope (pure) / scope → tools for `defineAppMcp`, a token's expanded scopes / transport wiring |
+| `mcp-tools.ts` / `mcp-scopes.ts` / `mcp.ts` / `mcp-dispatch.ts` | tool derivation, each tool's scope (pure) / scope → tools for `defineAppMcp`, a token's scopes / transport / one call |
 | `test-ctx.ts` | `adminTestCtx({ actor?, granted? })` — the `CrudCtx` a test hands a page or a CRUD call; `staticAuthz` over a grant list, its own audit log. What `x g admin:page`'s emitted render test calls |
 | `jobs/` | the jobs dashboard: entities, repos, the where translation, actions, labels, resources, the overview and its `/_x` tab |
 | `batch-matching.ts` / `audit-schema.ts` | a set-based "all matching" / the audit table's DDL, a leaf |
@@ -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.8.0",
+  "version": "31.0.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.8.0",
-    "@ultimat3/ai": "30.8.0",
-    "@ultimat3/cache": "30.8.0",
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/db": "30.8.0",
-    "@ultimat3/entity": "30.8.0",
-    "@ultimat3/http": "30.8.0",
-    "@ultimat3/i18n": "30.8.0",
-    "@ultimat3/jobs": "30.8.0",
-    "@ultimat3/mcp": "30.8.0",
-    "@ultimat3/money": "30.8.0",
-    "@ultimat3/policy": "30.8.0",
-    "@ultimat3/query": "30.8.0",
-    "@ultimat3/render": "30.8.0",
-    "@ultimat3/schema": "30.8.0",
-    "@ultimat3/ui": "30.8.0"
+    "@ultimat3/action": "31.0.0",
+    "@ultimat3/ai": "31.0.0",
+    "@ultimat3/cache": "31.0.0",
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/db": "31.0.0",
+    "@ultimat3/entity": "31.0.0",
+    "@ultimat3/http": "31.0.0",
+    "@ultimat3/i18n": "31.0.0",
+    "@ultimat3/jobs": "31.0.0",
+    "@ultimat3/mcp": "31.0.0",
+    "@ultimat3/money": "31.0.0",
+    "@ultimat3/policy": "31.0.0",
+    "@ultimat3/query": "31.0.0",
+    "@ultimat3/render": "31.0.0",
+    "@ultimat3/schema": "31.0.0",
+    "@ultimat3/ui": "31.0.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/entity-columns.ts

@@ -5,6 +5,8 @@
 // physical columns. And a foreign key is read back from `$describe()`, because the binding
 // that turns `() => orgs.id` into `"orgs.id"` is private to @ultimat3/entity.
 
+import { isUltimateError } from '@ultimat3/core';
+import { SchemaUnsupportedError, toWireSchema, type WireJsonSchema } from '@ultimat3/schema';
 import { AdminFieldUnsupportedError } from './errors';
 import type { AdminColumnMeta, AdminEntity } from './registry';
 
@@ -31,6 +33,12 @@ export interface AdminColumnFacts {
   readonly length?: number;
   readonly values?: readonly string[];
   readonly references?: AdminColumnReference;
+  /**
+   * What a `json()` or `arrayOf()` value is, as JSON Schema: the column's own schema, so an MCP
+   * argument is typed by the one judge of the value. `{}` (any) where none can be derived. Absent
+   * on every other kind, whose scalar type the field type already says. SQL NULL is `nullable`.
+   */
+  readonly valueSchema?: WireJsonSchema;
 }
 
 const parseReference = (entity: string, property: string, target: string): AdminColumnReference => {
@@ -61,25 +69,49 @@ const referencesOf = (entity: AdminEntity): ReadonlyMap<string, AdminColumnRefer
   return out;
 };
 
+/**
+ * The declared schema as a tool argument, or `{}` when it cannot be said (`X_SCHEMA_UNSUPPORTED`)
+ * — permissive, so the entity's own parse still judges the value. Any other throw is a defect.
+ */
+const declaredSchema = (schema: unknown): WireJsonSchema => {
+  if (schema === undefined) return {};
+  try {
+    return toWireSchema(schema);
+  } catch (error) {
+    if (isUltimateError(error) && error.code === SchemaUnsupportedError.code) return {};
+    throw error;
+  }
+};
+
+/** The VALUE's shape; whether the column also takes SQL NULL is `nullable`, beside it. */
+const valueSchemaOf = (meta: AdminColumnMeta): WireJsonSchema | undefined => {
+  if (meta.kind !== 'jsonb' && meta.kind !== 'array') return undefined;
+  return meta.kind === 'array' ? { type: 'array' } : declaredSchema(meta.schema);
+};
+
 const factsFor = (
   name: string,
   meta: AdminColumnMeta,
   primaryKey: boolean,
   references: AdminColumnReference | undefined,
-): AdminColumnFacts => ({
-  name,
-  kind: meta.kind,
-  nullable: !meta.notNull,
-  primaryKey,
-  unique: meta.unique,
-  index: meta.index,
-  // A value the writer never supplies. `.default('free')` is a starting value the operator
-  // may still change, so it stays writable — only a generated one is read-only.
-  generated: meta.default?.kind === 'generated' || meta.onUpdate !== undefined,
-  ...(meta.length === undefined ? {} : { length: meta.length }),
-  ...(meta.values === undefined ? {} : { values: meta.values }),
-  ...(references === undefined ? {} : { references }),
-});
+): AdminColumnFacts => {
+  const valueSchema = valueSchemaOf(meta);
+  return {
+    name,
+    kind: meta.kind,
+    nullable: !meta.notNull,
+    primaryKey,
+    unique: meta.unique,
+    index: meta.index,
+    // A value the writer never supplies. `.default('free')` is a starting value the operator
+    // may still change, so it stays writable — only a generated one is read-only.
+    generated: meta.default?.kind === 'generated' || meta.onUpdate !== undefined,
+    ...(meta.length === undefined ? {} : { length: meta.length }),
+    ...(meta.values === undefined ? {} : { values: meta.values }),
+    ...(references === undefined ? {} : { references }),
+    ...(valueSchema === undefined ? {} : { valueSchema }),
+  };
+};
 
 const factsOf = (entity: AdminEntity, sealed: boolean): readonly AdminColumnFacts[] => {
   const references = referencesOf(entity);

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,