@ultimat3/admin 23.0.0 → 25.0.0

package/src/dev/server.ts

@@ -4,11 +4,11 @@
 
 // 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 `devShellStyle()`, same reason as `data.ts`.
-import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
-import { FRAMEWORK_CATALOG_LOCALE, translatorFor } from '@ultimat3/i18n';
+import { DEFAULT_ENVIRONMENT, escapeHtml, tryResolveEnvironment } from '@ultimat3/core';
 import type { ColorRole } from '@ultimat3/ui';
 import { DevDashboardInProdError } from '../errors';
 import { defaultDevSources } from './data';
+import { t } from './dev-t';
 import type { DevSources } from './facts';
 import { type DevPanel, type PanelPayload, panelPayload } from './panel';
 import { cachePanel } from './panel-cache';
@@ -20,6 +20,7 @@ import { manifestPanel } from './panel-manifest';
 import { policyPanel } from './panel-policy';
 import { routesPanel } from './panel-routes';
 import { timelinePanel } from './panel-timeline';
+import { WATERFALL_STYLE } from './timeline-style';
 
 export const DEV_PANELS: readonly DevPanel[] = [
   routesPanel,
@@ -43,6 +44,13 @@ export interface DevDashboardOptions {
   readonly basePath?: string;
   readonly sources?: DevSources;
   readonly panels?: readonly DevPanel[];
+  /**
+   * The app surface's stylesheet URL — what `<link rel="stylesheet">` on an `app/` document carries.
+   * A drawn panel (the jobs tab) renders ui's own components, whose rules live there and not in the
+   * inlined shell; the host that mounts `/_x` is the one that knows the content-hashed URL. Asked
+   * per request, because a rebuild under `x dev` moves the hash. Absent or `undefined`: no link.
+   */
+  readonly stylesheetHref?: () => string | undefined;
 }
 
 const envOf = (name: string): string | undefined => {
@@ -85,10 +93,11 @@ const jsonResponse = (body: unknown, status = 200): Response =>
     headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
   });
 
-const escapeHtml = (value: string): string =>
-  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-
-/** The six roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. */
+/**
+ * The roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. The chart
+ * series are the timeline's span kinds — `chart-*` is contrast-gated against both surfaces, and
+ * every kind is named in text beside its bar, so colour is never the only key.
+ */
 const SHELL_ROLES = [
   'bg',
   'surface-raised',
@@ -96,6 +105,13 @@ const SHELL_ROLES = [
   'fg-muted',
   'line',
   'accent',
+  'chart-1',
+  'chart-2',
+  'chart-3',
+  'chart-4',
+  'chart-5',
+  'chart-6',
+  'chart-7',
 ] as const satisfies readonly ColorRole[];
 
 const SHELL_LAYOUT = `
@@ -110,7 +126,7 @@ p.question { color: rgb(var(--x-color-fg-muted)); margin: 0 0 1rem; }
 pre { background: rgb(var(--x-color-surface-raised)); border: 1px solid rgb(var(--x-color-line));
   padding: 1rem; overflow: auto; }
 :focus-visible { outline: 2px solid rgb(var(--x-color-accent)); outline-offset: 2px; }
-`;
+${WATERFALL_STYLE}`;
 
 let stylePromise: Promise<string> | undefined;
 
@@ -157,15 +173,10 @@ html[data-theme="dark"] { ${block('dark')} }
 ${SHELL_LAYOUT}`;
 }
 
-/**
- * /_x is the framework's own tool, in the framework's own locale (`<html lang="en">` below): its
- * strings are registered under `FRAMEWORK_CATALOG_LOCALE` only, so the AMBIENT locale — the app's,
- * `es-co` for an app that defaults to it — answered `⟦dev.panel.mail.title⟧` for every tab.
- */
-const t = (key: string): string => translatorFor(FRAMEWORK_CATALOG_LOCALE)(key);
-
 function shell(
   style: string,
+  /** The app surface's stylesheet, linked BEFORE the shell's `<style>` so the shell wins ties. */
+  stylesheetHref: string | undefined,
   basePath: string,
   panels: readonly DevPanel[],
   active: DevPanel,
@@ -184,7 +195,11 @@ function shell(
 <html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="robots" content="noindex, nofollow">
-<title>_x · ${escapeHtml(active.key)}</title><style>${style}</style></head>
+<title>_x · ${escapeHtml(active.key)}</title>${
+    stylesheetHref === undefined
+      ? ''
+      : `<link rel="stylesheet" href="${escapeHtml(stylesheetHref)}">`
+  }<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(t(active.questionKey))}</p>
@@ -241,8 +256,19 @@ export function devDashboard(opts: DevDashboardOptions = {}): DevDashboard {
       if (wantsJson) return jsonResponse(payload, payload.ok ? 200 : 500);
       const tabPath = `${basePath}/${panel.key}`;
       const drawn =
-        payload.ok && panel.html !== undefined ? await panel.html(url.searchParams, tabPath) : null;
-      return new Response(shell(await devShellStyle(), basePath, panels, panel, payload, drawn), {
+        payload.ok && panel.html !== undefined
+          ? await panel.html(url.searchParams, tabPath, payload.data)
+          : null;
+      const page = shell(
+        await devShellStyle(),
+        opts.stylesheetHref?.(),
+        basePath,
+        panels,
+        panel,
+        payload,
+        drawn,
+      );
+      return new Response(page, {
         status: 200,
         headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' },
       });

package/src/dev/sql-runner.ts

@@ -0,0 +1,31 @@
+// 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.
+
+import { type DbClient, readOnlyQuery } from '@ultimat3/db';
+import type { SqlResult } from './facts';
+
+/**
+ * The most rows the panel asks the server for. It draws a grid, not an export: a cursor fetches
+ * this many and the rest of a `select * from events` is never materialised in the dev process.
+ */
+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.
+ */
+export function readOnlySql(client: DbClient): (sql: string) => Promise<SqlResult> {
+  return async (sql) => {
+    const started = performance.now();
+    const { rows } = await readOnlyQuery<Readonly<Record<string, unknown>>>(sql, {
+      client,
+      maxRows: DEV_SQL_MAX_ROWS,
+    });
+    const elapsedMs = Math.round(performance.now() - started);
+    const columns = Object.keys(rows[0] ?? {});
+    return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
+  };
+}

package/src/dev/timeline-style.ts

@@ -0,0 +1,47 @@
+// The `/_x` timeline waterfall's rules, inlined into the shell's one `<style>` (`server.ts`) — /_x
+// has no stylesheet pipeline, and the CSP hash a host computes is of that whole text. Colours are
+// the shell's `--x-color-*` tokens only; each span kind takes one `chart-*` series role.
+
+import { SPAN_KINDS } from './timeline-waterfall';
+
+/**
+ * The timeline's waterfall (`timeline-waterfall.ts`): a label column, a track whose bar is placed
+ * by the row's own `--offset`/`--width` (server-computed shares), and the duration. Below 720px the
+ * label takes its own line, so a long SQL text never squeezes the track to nothing on a phone.
+ */
+export const WATERFALL_STYLE = `
+h2 { font-size: .875rem; margin: 0 0 .5rem; }
+.tl { display: grid; gap: 1.5rem; }
+@media (min-width: 1024px) { .tl { grid-template-columns: minmax(12rem, 18rem) minmax(0, 1fr); } }
+.tl-requests ol, .tl-kinds, .tl-flame, .tl-loops ul { list-style: none; margin: 0; padding: 0; }
+.tl-requests li { display: flex; justify-content: space-between; gap: .5rem; padding: .25rem 0;
+  border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-requests a { overflow-wrap: anywhere; }
+.tl-requests a[aria-current] { color: rgb(var(--x-color-fg)); font-weight: 700; }
+.tl-ms { color: rgb(var(--x-color-fg-muted)); white-space: nowrap; font-variant-numeric: tabular-nums; }
+.tl-kinds { display: flex; flex-wrap: wrap; gap: .25rem 1rem; margin-bottom: 1rem; }
+.tl-swatch { display: inline-block; inline-size: .75rem; block-size: .75rem; border-radius: 2px;
+  margin-inline-end: .375rem; vertical-align: -1px; background: rgb(var(--tl-color)); }
+.tl-row { display: grid; grid-template-columns: minmax(0, 1fr) 4.5rem; gap: .125rem .75rem;
+  align-items: center; padding: .25rem 0; border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-label { grid-column: 1 / -1; display: flex; gap: .5rem; align-items: baseline; min-inline-size: 0;
+  padding-inline-start: calc(var(--depth) * .75rem); }
+@media (min-width: 720px) {
+  .tl-row { grid-template-columns: minmax(0, 22rem) minmax(0, 1fr) 4.5rem; }
+  .tl-label { grid-column: auto; }
+}
+.tl-kind { flex: none; padding: 0 .375rem; border-radius: 2px; font-size: .75rem;
+  border: 1px solid rgb(var(--tl-color)); color: rgb(var(--x-color-fg)); }
+.tl-name { flex: none; }
+.tl-detail { min-inline-size: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  color: rgb(var(--x-color-fg-muted)); }
+.tl-track { position: relative; block-size: .875rem; border-radius: 2px;
+  background: rgb(var(--x-color-line) / .35); }
+.tl-bar { position: absolute; inset-block: 0; inset-inline-start: var(--offset);
+  inline-size: max(var(--width), 2px); border-radius: 2px; background: rgb(var(--tl-color)); }
+.tl-row > .tl-ms { text-align: end; }
+.tl-loops { margin-top: 1.5rem; }
+.tl-loops li { padding: .5rem 0; border-bottom: 1px solid rgb(var(--x-color-line)); }
+.tl-empty { color: rgb(var(--x-color-fg-muted)); }
+${SPAN_KINDS.map((kind, index) => `[data-kind="${kind}"] { --tl-color: var(--x-color-chart-${index + 1}); }`).join('\n')}
+`;

package/src/dev/timeline-waterfall.ts

@@ -0,0 +1,96 @@
+// The `/_x` timeline tab, drawn: the selected request's spans as a waterfall — one row per span,
+// indented under its parent, its bar placed and sized by the server from the payload's own
+// `offset`/`width` — beside the recent requests, the time per kind and the N+1 verdicts. Plain
+// escaped HTML on the shell's tokens: `/_x` loads no Solid and no stylesheet pipeline to draw it.
+
+import { escapeHtml } from '@ultimat3/core';
+import { t } from './dev-t';
+import type { SpanKind, StatementLoopFact } from './facts';
+import type { FlameRow, TimelinePanelData } from './panel-timeline';
+
+/** Every kind a span can be, in the order the legend lists them — and the colour slot each takes. */
+export const SPAN_KINDS: readonly SpanKind[] = [
+  'http',
+  'render',
+  'action',
+  'policy',
+  'sql',
+  'cache',
+  'job',
+];
+
+/** `/_x` is the framework's English tool; a duration reads to a tenth of a millisecond. */
+const MS = new Intl.NumberFormat('en', { maximumFractionDigits: 1 });
+const ms = (value: number): string => t('dev.panel.timeline.ms', { ms: MS.format(value) });
+
+/** A 0..1 share as a CSS percentage: two decimals at most, never `-0`, clamped to the track. */
+const percent = (share: number): string => {
+  const clamped = Number.isFinite(share) ? Math.min(1, Math.max(0, share)) : 0;
+  const text = (clamped * 100).toFixed(2).replace(/\.?0+$/, '');
+  return `${text === '-0' ? '0' : text}%`;
+};
+
+const kindLabel = (kind: SpanKind): string => t(`dev.panel.timeline.kind.${kind}`);
+
+const kindTag = (kind: SpanKind): string =>
+  `<span class="tl-kind">${escapeHtml(kindLabel(kind))}</span>`;
+
+function requestList(data: TimelinePanelData, tabPath: string): string {
+  const shown = data.selected?.requestId;
+  const items = data.requests
+    .map((request) => {
+      const href = `${tabPath}?requestId=${encodeURIComponent(request.requestId)}`;
+      const current = request.requestId === shown ? ' aria-current="true"' : '';
+      return `<li><a href="${escapeHtml(href)}"${current}>${escapeHtml(request.path)}</a> <span class="tl-ms">${escapeHtml(ms(request.totalMs))}</span></li>`;
+    })
+    .join('');
+  const title = escapeHtml(t('dev.panel.timeline.requests'));
+  return `<nav class="tl-requests" aria-label="${title}"><h2>${title}</h2><ol>${items}</ol></nav>`;
+}
+
+function kindTotals(data: TimelinePanelData): string {
+  const items = SPAN_KINDS.filter((kind) => Object.hasOwn(data.totalsByKind, kind))
+    .map(
+      (kind) =>
+        `<li><span class="tl-swatch" data-kind="${kind}" aria-hidden="true"></span>${escapeHtml(kindLabel(kind))} <span class="tl-ms">${escapeHtml(ms(data.totalsByKind[kind] ?? 0))}</span></li>`,
+    )
+    .join('');
+  return `<ul class="tl-kinds" aria-label="${escapeHtml(t('dev.panel.timeline.byKind'))}">${items}</ul>`;
+}
+
+function row(flame: FlameRow): string {
+  const { span } = flame;
+  const style = `--depth:${flame.depth};--offset:${percent(flame.offset)};--width:${percent(flame.width)}`;
+  const detail =
+    span.detail === ''
+      ? ''
+      : `<code class="tl-detail" title="${escapeHtml(span.detail)}">${escapeHtml(span.detail)}</code>`;
+  return `<li class="tl-row" data-kind="${span.kind}" style="${style}"><span class="tl-label">${kindTag(span.kind)} <span class="tl-name">${escapeHtml(span.name)}</span>${detail}</span><span class="tl-track" aria-hidden="true"><span class="tl-bar"></span></span><span class="tl-ms">${escapeHtml(ms(span.durationMs))}</span></li>`;
+}
+
+function verdicts(loops: readonly StatementLoopFact[] | null): string {
+  const title = `<h2>${escapeHtml(t('dev.panel.timeline.nPlusOne.title'))}</h2>`;
+  if (loops === null) {
+    return `<section class="tl-loops">${title}<p class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.unwired'))}</p></section>`;
+  }
+  if (loops.length === 0) {
+    return `<section class="tl-loops">${title}<p class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.clean'))}</p></section>`;
+  }
+  const items = loops
+    .map(
+      (loop) =>
+        `<li><strong>${escapeHtml(loop.code)}</strong> ${escapeHtml(loop.cause)}<br><span class="question">${escapeHtml(t('dev.panel.timeline.nPlusOne.fix'))}</span> <code>${escapeHtml(loop.fix)}</code></li>`,
+    )
+    .join('');
+  return `<section class="tl-loops">${title}<ul>${items}</ul></section>`;
+}
+
+/** The tab body. Pure over the panel's data, so the `--json` payload and the drawing agree. */
+export function timelineHtml(data: TimelinePanelData, tabPath: string): string {
+  const selected = data.selected;
+  if (selected === null) {
+    return `<p class="tl-empty">${escapeHtml(t('dev.panel.timeline.empty'))}</p>`;
+  }
+  const heading = `${selected.method} ${selected.path} · ${selected.status} · ${ms(selected.totalMs)}`;
+  return `<div class="tl">${requestList(data, tabPath)}<section class="tl-trace" aria-labelledby="tl-heading"><h2 id="tl-heading">${escapeHtml(heading)}</h2>${kindTotals(data)}<ol class="tl-flame" aria-label="${escapeHtml(t('dev.panel.timeline.spans'))}">${data.flame.map(row).join('')}</ol>${verdicts(data.nPlusOne)}</section></div>`;
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 // The X_* codes owned by @ultimat3/admin. Every one names the exact edit that fixes it,
 // because the two dashboards fail at boot (bad registry, bad mount) where an agent has no
 // stack trace to reason from — only the message.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { NotImplementedError, registerErrorCodes, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const ADMIN_OWNED_ERROR_CODES = [
@@ -32,8 +32,8 @@ export const ADMIN_OWNED_ERROR_CODES = [
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `DevSourceUnavailableError` throws it; this package
- * neither titles nor registers it, because the owner's title is the only one that may exist.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `DevSourceUnavailableError` IS core's
+ * `NotImplementedError`, narrowed; this package neither constructs, titles nor registers the code, because the owner's title is the only one that may exist.
  */
 export const ADMIN_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
 
@@ -254,11 +254,15 @@ export class AdminPagePathInvalidError extends UltimateError {
  * 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
  * empty panel, because an empty panel reads as "nothing happened".
+ *
+ * Core's NotImplementedError and not a sibling of it: core is the one constructor of the code.
+ * A class of its own all the same, because a panel degrades on "this source is not wired" and on
+ * nothing wider — a wired source whose driver answers X_NOT_IMPLEMENTED is a diagnostic, not an
+ * unwired tab (dev/panel-degrade.test.ts).
  */
-export class DevSourceUnavailableError extends UltimateError {
+export class DevSourceUnavailableError extends NotImplementedError {
   constructor(input: { source: string; panel: string; wiring?: string }) {
     super({
-      code: 'X_NOT_IMPLEMENTED',
       cause: `the /_x ${input.panel} panel needs the "${input.source}" source, which is not wired in this process`,
       // `wiring`, when supplied, replaces the whole `defaultDevSources(...)` argument text —
       // the default `hooks: { <source> }` phrasing is only valid when the source really is a

package/src/form-decode.ts

@@ -5,7 +5,9 @@
 // It converts and never validates: a value that will not convert is passed through as the string
 // that was typed, so the schema refuses it in its own words against the field that carried it.
 
+import { numeric } from '@ultimat3/schema';
 import type { AdminField } from './fields';
+import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
 
 /** The posted name of a money field's currency, beside the minor-unit amount under the field's own. */
@@ -13,6 +15,39 @@ export const currencyFieldOf = (field: string): string => `${field}.currency`;
 
 type Posted = Readonly<Record<string, unknown>>;
 
+/**
+ * What a date control is RENDERED with: `<input type="date">` wants `YYYY-MM-DD`, `datetime-local`
+ * wants `YYYY-MM-DDTHH:mm`. One function for the widget that draws the box and for the decode that
+ * reads it back, so "the operator left it as it was" is a comparison of one text with itself.
+ */
+export const datetimeInputValue = (iso: string, precision: 'date' | 'instant'): string =>
+  iso.slice(0, precision === 'date' ? 10 : 16);
+
+const isoOf = (value: unknown): string | undefined =>
+  value instanceof Date
+    ? Number.isNaN(value.getTime())
+      ? undefined
+      : value.toISOString()
+    : typeof value === 'string'
+      ? value
+      : undefined;
+
+/**
+ * An instant posted back as the box rendered it. `datetime-local` holds minutes, so writing what
+ * came back turned `10:20:45.123` into `10:20:00.000` on every edit of ANY field — a change nobody
+ * made, recorded in the audit diff as theirs. Such a field is left out of the patch and the stored
+ * instant stands. A calendar date carries every digit it has and is never in this position.
+ */
+const untouchedInstant = (
+  field: AdminField,
+  raw: string | undefined,
+  before: AdminRow,
+): boolean => {
+  if (field.widget !== 'datetime' || field.type === 'date' || raw === undefined) return false;
+  const stored = isoOf(before[field.name]);
+  return stored !== undefined && raw === datetimeInputValue(stored, 'instant');
+};
+
 /** The last value a posted name carried, as text. A repeated name arrives as a list. */
 export const posted = (form: Posted, name: string): string | undefined => {
   if (!Object.hasOwn(form, name)) return undefined;
@@ -38,10 +73,15 @@ const TYPED: ReadonlySet<AdminField['widget']> = new Set([
 const blank = (field: AdminField): unknown =>
   field.required && !TYPED.has(field.widget) ? '' : null;
 
-const numberOf = (raw: string): unknown => {
-  const parsed = Number(raw);
-  return Number.isFinite(parsed) ? parsed : raw;
-};
+/**
+ * Schema's own decimal reader, never `Number(raw)`: that reads hex, binary and octal too, so `0x10`
+ * in a money box was stored as `minor: 16`. Anything else is handed on as typed for the schema to
+ * refuse against the field. Whitespace never reaches here — `decodeField` blanks it first.
+ */
+const numberOf = (raw: string): unknown => numeric(raw) ?? raw;
+
+/** The widgets that hold a number: a box of only whitespace is as empty as `''` for them. */
+const NUMERIC: ReadonlySet<AdminField['widget']> = new Set(['money', 'number-input']);
 
 const jsonOf = (raw: string): unknown => {
   try {
@@ -57,6 +97,9 @@ function decodeField(field: AdminField, form: Posted): unknown {
   // An unchecked box posts nothing at all, so absence IS the answer for a checkbox.
   if (field.widget === 'checkbox') return raw !== undefined && raw !== 'false';
   if (raw === undefined || raw === '') return blank(field);
+  // `Number(' ')` is 0, so a space in an untouched optional number box was a write of 0 over a
+  // stored null — a change the audit diff then attributed to the operator.
+  if (NUMERIC.has(field.widget) && raw.trim() === '') return blank(field);
   switch (field.widget) {
     case 'number-input':
       return numberOf(raw);
@@ -79,13 +122,20 @@ function decodeField(field: AdminField, form: Posted): unknown {
 /**
  * Every field the form rendered, decoded. A sealed column rides along as the string that was
  * typed — `crud.ts` drops an empty one, which is what makes an untouched box mean "unchanged".
+ *
+ * `before` is the row an EDIT form was rendered from: an instant that comes back exactly as it was
+ * drawn is left out rather than rewritten at the control's precision. A create has none.
  */
 export function decodeForm(
   resource: AdminResource,
   form: Posted,
+  before?: AdminRow,
 ): Readonly<Record<string, unknown>> {
   const out: Record<string, unknown> = {};
-  for (const field of resource.formFields) out[field.name] = decodeField(field, form);
+  for (const field of resource.formFields) {
+    if (before !== undefined && untouchedInstant(field, posted(form, field.name), before)) continue;
+    out[field.name] = decodeField(field, form);
+  }
   for (const field of resource.secretFields) out[field.name] = posted(form, field.name) ?? '';
   return out;
 }

package/src/form.tsx

@@ -12,6 +12,7 @@ import type { AdminField } from './fields';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
 import { fieldsFor } from './resource-layout';
+import { VERSION_FIELD } from './row-version';
 import type { ValidationIssue } from './validate';
 import type { WidgetContext } from './widget-value';
 import { Widget } from './widgets';
@@ -28,6 +29,11 @@ export interface AdminFormProps<Row extends AdminRow> {
   readonly action: string;
   /** Where Cancel goes — the list for a create, the row for an edit. */
   readonly cancelHref: string;
+  /**
+   * An edit's `rowVersion()` of the row it was rendered from, posted back as `_version` so the
+   * write is refused if the row moved on meanwhile. `null` for a create, which has no row.
+   */
+  readonly version: string | null;
 }
 
 const issuesFor = (issues: readonly ValidationIssue[], field: string): readonly ValidationIssue[] =>
@@ -90,15 +96,23 @@ export function AdminForm<Row extends AdminRow>(props: AdminFormProps<Row>): JSX
   return (
     <Card header={<h2>{t(titleKey, { entity: t(props.resource.titleKey) })}</h2>}>
       <form class={styles['form']} method="post" action={props.action}>
+        {props.version === null ? null : (
+          <input type="hidden" name={VERSION_FIELD} value={props.version} />
+        )}
         {props.issues.length === 0 ? null : (
           <div class="x-admin-issues" role="alert" tabindex={-1}>
             <h3>{t('admin.form.issues')}</h3>
             <ul>
-              {props.issues.map((issue) => (
-                <li>
-                  <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issueText(issue)}
-                </li>
-              ))}
+              {props.issues.map((issue) =>
+                // The form's own issue (the row changed under it) names no control to jump to.
+                issue.path === VERSION_FIELD ? (
+                  <li>{issueText(issue)}</li>
+                ) : (
+                  <li>
+                    <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issueText(issue)}
+                  </li>
+                ),
+              )}
             </ul>
           </div>
         )}

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   type AdminActionButton,
   actionButtons,
   actionDecisions,
+  adminPermissionForAction,
   decideAction,
   type InvokeInput,
   type InvokeResult,
@@ -77,24 +78,22 @@ export {
   deniedDraft,
   diffRows,
   memoryAuditLog,
-  REDACTED,
 } from './audit';
 export {
   type PostgresAuditLogOptions,
   postgresAuditLog,
-  SQL_ADMIN_AUDIT_INSERT,
 } from './audit-pg';
-export { ADMIN_AUDIT_TABLE, SQL_ADMIN_AUDIT_TABLE } from './audit-schema';
+// The audit table's DDL is `@ultimat3/admin/schema`'s alone — one import path for one statement.
 export {
   type AdminActor,
   type AdminAuthz,
   type AdminAuthzQuery,
   type AdminDecision,
   type AdminSubject,
-  allowed,
+  adminAllowed,
+  adminDenied,
   anonymousAuthz,
   decideAll,
-  denied,
   expandPermissions,
   isAllowed,
   staticAuthz,
@@ -104,7 +103,6 @@ export {
   type AdminBatchInput,
   type AdminBatchResult,
   BATCH_NOT_OFFERED_REASON,
-  BATCH_QUEUED_REASON,
   type BatchEnqueue,
   type BatchRow,
   type BatchRowOutcome,
@@ -124,7 +122,9 @@ export {
   batchEnqueue,
 } from './batch-job';
 export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
+export { BATCH_QUEUED_REASON } from './batch-queue';
 export {
+  type AdminUpdateOptions,
   adminCreate,
   adminDestroy,
   adminDetail,
@@ -197,7 +197,7 @@ export { currencyFieldOf, decodeForm, 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 { AdminLayout, type AdminLayoutProps, actorLabel } from './layout';
+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';
@@ -229,12 +229,14 @@ export {
 } from './list-scope';
 export { AdminScopeTabs, type AdminScopeTabsProps } from './list-scope-tabs';
 export {
+  type AdminMcpActor,
   type AdminMcpOptions,
   type AdminToolResult,
   adminMcp,
   callAdminTool,
   type McpInput,
 } from './mcp';
+export { adminTokenScopes, adminToolScopes } from './mcp-scopes';
 export {
   type AdminMcpTool,
   type AdminToolField,
@@ -290,7 +292,6 @@ export {
   ruleFor,
 } from './permissions';
 export {
-  adminPermissions,
   declareAdminPermissions,
   type PolicyAuthzInput,
   policyAuthz,
@@ -341,8 +342,8 @@ export {
   labelOf,
   type RelationData,
   type RelationNeed,
+  relationDataFor,
   relationNeeds,
-  relationsFor,
 } from './relations';
 export { ComputedCell, TRUNCATE_AT } from './renderers';
 export { adminEntitiesOf, adminRepoFor, adminTablesOf } from './repo-entity';
@@ -382,6 +383,7 @@ export {
   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,

package/src/jobs/fleet-repo.ts

@@ -14,18 +14,30 @@ const comparable = (value: unknown): string | number => {
   if (value instanceof Date) return value.getTime();
   if (typeof value === 'number') return value;
   if (typeof value === 'boolean') return value ? 1 : 0;
-  return value === null || value === undefined ? '' : String(value);
+  return String(value);
 };
 
-/** Code-unit order, never a collation: the same set reads the same way on every machine. */
+const absent = (value: unknown): boolean => value === null || value === undefined;
+
+/**
+ * Code-unit order, never a collation: the same set reads the same way on every machine. NULL is
+ * the LARGEST value — last ascending, first descending — as the database orders a nullable sort
+ * key and as `repo-entity.ts` seeks one; it read as `''` here, which sorted it as a zero.
+ */
 const order = (a: unknown, b: unknown): number => {
+  if (absent(a) || absent(b)) return absent(a) && absent(b) ? 0 : absent(a) ? 1 : -1;
   const x = comparable(a);
   const y = comparable(b);
   return x < y ? -1 : x > y ? 1 : 0;
 };
 
-/** A cursor carries its value as text (`pagination.ts`); read back as the column's own type. */
+/**
+ * A cursor carries its value as text (`pagination.ts`), or `null` for a row that held none; read
+ * back as the type of the row it is compared with. A `null` bound stays `null` — `new Date(null)`
+ * is the epoch and `new Date('')` is NaN, and either made the page after a NULL row the wrong one.
+ */
 const boundValue = (row: AdminRow, bound: KeysetBound, field: string): unknown => {
+  if (bound.value === null) return null;
   const held = row[field];
   if (held instanceof Date) return new Date(bound.value);
   if (typeof held === 'number') return Number(bound.value);