@ultimat3/admin 22.14.0 → 23.0.0

package/src/jobs/job-where.ts

@@ -0,0 +1,170 @@
+// The admin's predicate IR → the job store's own filters. The jobs list is read through
+// `JobIntrospection`, whose `list` and bulk verbs answer a FIXED set of predicates; this is the one
+// translation, shared by the list, a row's lookup and "all matching", and anything it cannot say
+// is refused by name — never dropped, which would widen the operator's list (or their bulk call).
+
+import type { BulkFilter, JobFilter, JobState } from '@ultimat3/jobs';
+import { isJobState } from '@ultimat3/jobs';
+import { AdminFilterInvalidError } from '../errors';
+import type { AdminFilter } from '../registry';
+
+/** The resource the job rows are, named once for every refusal. */
+export const JOBS_RESOURCE = 'x_jobs';
+
+/** What the store answers, in the URL's own spelling — the refusal's `known` list. */
+const ANSWERED = [
+  'f.id (starts with)',
+  'f.id.eq',
+  'f.name',
+  'f.queue',
+  'f.state',
+  'f.tenantId',
+  'f.createdAt.gte',
+  'f.createdAt.lte',
+] as const;
+
+/** A translated `where`: the store's filter, and the one predicate it has no column for. */
+export interface JobWhere {
+  readonly filter: Omit<JobFilter, 'limit' | 'after' | 'before'>;
+  /** `id eq`: the store matches a prefix, so an exact id is checked on the row. */
+  readonly exactId?: string;
+  /** Two predicates no row satisfies at once (`state = dead` and `state = done`). */
+  readonly empty: boolean;
+}
+
+const refuse = (filter: AdminFilter, cause: string): never => {
+  throw new AdminFilterInvalidError({
+    entity: JOBS_RESOURCE,
+    asked: `f.${filter.field}.${filter.op}`,
+    cause,
+    known: ANSWERED,
+  });
+};
+
+const text = (filter: AdminFilter): string =>
+  typeof filter.value === 'string'
+    ? filter.value
+    : refuse(filter, 'takes one value as text — the job store compares no list here');
+
+const instantMs = (filter: AdminFilter): number => {
+  const ms = Date.parse(text(filter));
+  return Number.isFinite(ms) ? ms : refuse(filter, 'takes an ISO-8601 instant');
+};
+
+type Mutable = { -readonly [K in keyof JobWhere['filter']]: JobWhere['filter'][K] };
+
+/** Set one key, or notice that two predicates contradict each other. */
+function put<K extends keyof Mutable>(
+  out: Mutable,
+  key: K,
+  value: NonNullable<Mutable[K]>,
+  narrower: (a: NonNullable<Mutable[K]>, b: NonNullable<Mutable[K]>) => Mutable[K] | null,
+): boolean {
+  const held = out[key];
+  if (held === undefined || held === null) {
+    out[key] = value;
+    return true;
+  }
+  const merged = narrower(held as NonNullable<Mutable[K]>, value);
+  if (merged === null) return false;
+  out[key] = merged;
+  return true;
+}
+
+const same = <T>(a: T, b: T): T | null => (a === b ? a : null);
+
+export function jobWhere(where: readonly AdminFilter[]): JobWhere {
+  const out: Mutable = {};
+  let exactId: string | undefined;
+  let empty = false;
+  const keep = (holds: boolean): void => {
+    if (!holds) empty = true;
+  };
+  for (const filter of where) {
+    const key = `${filter.field}.${filter.op}`;
+    switch (key) {
+      case 'state.eq': {
+        const state = text(filter);
+        if (!isJobState(state)) refuse(filter, 'is not a job state');
+        keep(put(out, 'state', state as JobState, same));
+        break;
+      }
+      case 'queue.eq':
+        keep(put(out, 'queue', text(filter), same));
+        break;
+      case 'name.eq':
+        keep(put(out, 'name', text(filter), same));
+        break;
+      case 'tenantId.eq':
+        keep(put(out, 'tenantId', text(filter), same));
+        break;
+      // A job id is opaque and pasted from a log line by its first characters: the store's own
+      // search is by prefix, so the id box's `contains` is answered as "starts with".
+      case 'id.contains':
+        keep(
+          put(out, 'idPrefix', text(filter), (a, b) =>
+            a.startsWith(b) ? a : b.startsWith(a) ? b : null,
+          ),
+        );
+        break;
+      case 'id.eq': {
+        const id = text(filter);
+        if (exactId !== undefined && exactId !== id) empty = true;
+        exactId = id;
+        keep(put(out, 'idPrefix', id, (a, b) => (b.startsWith(a) ? b : null)));
+        break;
+      }
+      case 'createdAt.gte':
+      case 'createdAt.gt': {
+        const from = instantMs(filter) + (filter.op === 'gt' ? 1 : 0);
+        put(out, 'createdFrom', from, (a, b) => Math.max(a, b));
+        break;
+      }
+      // The store's upper bound is exclusive; `lte` includes its own millisecond.
+      case 'createdAt.lt':
+      case 'createdAt.lte': {
+        const to = instantMs(filter) + (filter.op === 'lte' ? 1 : 0);
+        put(out, 'createdTo', to, (a, b) => Math.min(a, b));
+        break;
+      }
+      default:
+        refuse(filter, 'is not a predicate the job store answers');
+    }
+  }
+  if (
+    out.createdFrom !== undefined &&
+    out.createdTo !== undefined &&
+    out.createdFrom >= out.createdTo
+  ) {
+    empty = true;
+  }
+  return { filter: out, ...(exactId === undefined ? {} : { exactId }), empty };
+}
+
+/**
+ * The same `where` as a BULK verb's filter, which answers fewer predicates than a page does: a
+ * state (required — "every job" is never one call), a queue, a name, a tenant. An id or a time
+ * range is a selection the operator checks row by row, and is refused by name here.
+ */
+export function bulkWhere(where: readonly AdminFilter[]): BulkFilter | null {
+  const translated = jobWhere(where);
+  if (translated.empty) return null;
+  const { state, queue, name, tenantId, idPrefix, createdFrom, createdTo } = translated.filter;
+  const narrowed = idPrefix !== undefined || createdFrom !== undefined || createdTo !== undefined;
+  if (narrowed || state === undefined) {
+    throw new AdminFilterInvalidError({
+      entity: JOBS_RESOURCE,
+      asked: narrowed ? 'all matching, narrowed by id or time' : 'all matching, over every state',
+      cause: narrowed
+        ? 'cannot be one bulk call: the store bulk-edits by state, queue, name and tenant only — check the rows instead'
+        : 'cannot be one bulk call: pick a state tab first, so "every job" is never one call',
+      known: ['scope=<state>', 'f.queue', 'f.name', 'f.tenantId'],
+    });
+  }
+  return {
+    state,
+    ...(queue === undefined ? {} : { queue }),
+    ...(name === undefined ? {} : { name }),
+    ...(tenantId === undefined ? {} : { tenantId }),
+  };
+}

package/src/jobs/operator.ts

@@ -0,0 +1,34 @@
+// The one door from the jobs screens to the queue: the process's own driver, read per call — the
+// boot installs it after `defineAdmin()` has run, and `x dev` swaps it — and its operator surface.
+// A process with no driver, or one that ships no operator surface, is refused with the fix.
+
+import {
+  DriverUnavailableError,
+  type JobDriver,
+  type JobIntrospection,
+  JobsNotImplementedError,
+  jobDriver,
+} from '@ultimat3/jobs';
+
+export interface JobsOperator {
+  readonly driver: JobDriver;
+  readonly introspect: JobIntrospection;
+}
+
+export function jobsOperator(): JobsOperator {
+  const driver = jobDriver();
+  if (driver === undefined) {
+    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(createMemoryDriver())',
+    });
+  }
+  if (driver.introspect === undefined) {
+    throw new JobsNotImplementedError({
+      feature: `the operator surface of the "${driver.name}" jobs driver`,
+      fix: 'call setJobDriver(createPgDriver()) at boot — the pg and memory drivers implement introspect',
+    });
+  }
+  return { driver, introspect: driver.introspect };
+}

package/src/jobs/overview-data.ts

@@ -0,0 +1,129 @@
+// What the jobs overview reads, and the arithmetic over it: queue depth from ONE `stats()`, the
+// worker registry, and the settle counters folded into a fixed number of bars per range. Pure apart
+// from `overviewData`, so the chart's bucketing is tested without a queue.
+
+import { expectedQueryLoop } from '@ultimat3/db';
+import { type CounterTotals, inspectQueues, type JobCounter } from '@ultimat3/jobs';
+import { AdminFilterInvalidError } from '../errors';
+import { jobsOperator } from './operator';
+
+/** The ranges the chart and the per-name table answer, and how many bars each is drawn in. */
+export const OVERVIEW_RANGES = {
+  '1h': { ms: 3_600_000, bars: 12 },
+  '24h': { ms: 86_400_000, bars: 24 },
+  '7d': { ms: 604_800_000, bars: 28 },
+  '30d': { ms: 2_592_000_000, bars: 30 },
+} as const;
+
+export type OverviewRange = keyof typeof OVERVIEW_RANGES;
+export const RANGE_PARAM = 'range';
+export const DEFAULT_RANGE: OverviewRange = '24h';
+const RANGES: ReadonlyMap<string, OverviewRange> = new Map(
+  (Object.keys(OVERVIEW_RANGES) as OverviewRange[]).map((key) => [key, key]),
+);
+
+/** `?range=` as one of the four; absent is the default, anything else is refused by name. */
+export function rangeOf(url: URL): OverviewRange {
+  const asked = url.searchParams.get(RANGE_PARAM);
+  if (asked === null || asked === '') return DEFAULT_RANGE;
+  const range = RANGES.get(asked);
+  if (range !== undefined) return range;
+  throw new AdminFilterInvalidError({
+    entity: 'jobs',
+    asked: `${RANGE_PARAM}=${asked}`,
+    cause: 'is not a range the overview draws',
+    known: [...RANGES.keys()].map((key) => `${RANGE_PARAM}=${key}`),
+  });
+}
+
+export interface OverviewBar {
+  readonly startMs: number;
+  readonly done: number;
+  /** Runs that ended badly: `failed` and `dead`. A retried attempt is not an ending. */
+  readonly failed: number;
+}
+
+/** Every bucket from `sinceMs` on, whatever tier it lives in, summed into `bars` equal bars. */
+export function barsOf(
+  counters: readonly JobCounter[],
+  range: OverviewRange,
+  nowMs: number,
+): readonly OverviewBar[] {
+  const { ms, bars } = OVERVIEW_RANGES[range];
+  const width = ms / bars;
+  const start = nowMs - ms;
+  const out = Array.from({ length: bars }, (_, index) => ({
+    startMs: start + index * width,
+    done: 0,
+    failed: 0,
+  }));
+  for (const bucket of counters) {
+    const index = Math.floor((bucket.bucketStart - start) / width);
+    const bar = out[Math.min(bars - 1, Math.max(0, index))];
+    if (bar === undefined) continue;
+    bar.done += bucket.done;
+    bar.failed += bucket.failed + bucket.dead;
+  }
+  return out;
+}
+
+export interface NameRow {
+  readonly name: string;
+  /** Runs that ended in the range: done, failed and dead. */
+  readonly volume: number;
+  /** Of those, the share that did not end done — `null` when none ended. */
+  readonly failureRate: number | null;
+  /** Mean attempt duration, retries included — `null` when nothing was attempted. */
+  readonly meanMs: number | null;
+}
+
+export function nameRowsOf(totals: readonly CounterTotals[]): readonly NameRow[] {
+  return totals.map((row) => {
+    const volume = row.done + row.failed + row.dead;
+    const attempts = volume + row.retried;
+    return {
+      name: row.job,
+      volume,
+      failureRate: volume === 0 ? null : (row.failed + row.dead) / volume,
+      meanMs: attempts === 0 ? null : row.durationMs / attempts,
+    };
+  });
+}
+
+export interface OverviewData {
+  readonly totals: Awaited<ReturnType<typeof inspectQueues>>['totals'];
+  readonly oldestReadyMs: number;
+  readonly workers: number;
+  readonly bars: readonly OverviewBar[];
+  readonly names: readonly NameRow[];
+}
+
+/**
+ * Two statements and one per job name that settled in the range: the totals say which names have
+ * buckets at all, and each one's buckets are read by name — the store keys counters by job. The
+ * loop is declared rather than hidden: it is bounded by the app's registered job names.
+ */
+export async function overviewData(range: OverviewRange, nowMs: number): Promise<OverviewData> {
+  const { driver, introspect } = jobsOperator();
+  const sinceMs = nowMs - OVERVIEW_RANGES[range].ms;
+  const [depth, workers, totals] = await Promise.all([
+    inspectQueues(driver),
+    introspect.workers(),
+    introspect.counterTotals(sinceMs),
+  ]);
+  const counters = await expectedQueryLoop(
+    'the jobs overview reads each settled job name’s counter buckets; the store keys them by name',
+    async () => {
+      const all: JobCounter[] = [];
+      for (const row of totals) all.push(...(await introspect.counters({ job: row.job, sinceMs })));
+      return all;
+    },
+  );
+  return {
+    totals: depth.totals,
+    oldestReadyMs: depth.oldestReadyMs,
+    workers: workers.length,
+    bars: barsOf(counters, range, nowMs),
+    names: nameRowsOf(totals),
+  };
+}

package/src/jobs/overview-tab.tsx

@@ -0,0 +1,61 @@
+// The `/_x` jobs tab's body: the SAME `JobsOverview` `/admin/jobs` renders, over this process's
+// own queue (the dev driver under `x dev`) — one jobs UI, not a second one in the dev panel. Only
+// ever reached by `dev/panel-jobs.ts`'s dynamic `import()`, so `/_x`'s mount graph stays free of it.
+
+import { createContext, runWithContext } from '@ultimat3/core';
+import { renderToHtml } from '@ultimat3/render/server';
+import { listHref } from '../list-request';
+import { adminMounts } from '../mounts';
+import { JOB_ENTITY } from './job-entities';
+import { JobsOverview } from './overview';
+import {
+  DEFAULT_RANGE,
+  OVERVIEW_RANGES,
+  type OverviewRange,
+  overviewData,
+  RANGE_PARAM,
+} from './overview-data';
+
+const isRange = (value: string | null): value is OverviewRange =>
+  value !== null && Object.hasOwn(OVERVIEW_RANGES, value);
+
+/**
+ * The overview as HTML, its links into the app's own admin when one is mounted — the lists live
+ * there — and into this tab's `--json` otherwise. `/_x` is the framework's tool, so it reads in
+ * the framework's locale and in UTC, stated rather than ambient.
+ */
+export async function jobsTabHtml(tabPath: string, params: URLSearchParams): Promise<string> {
+  const asked = params.get(RANGE_PARAM);
+  const range = isRange(asked) ? asked : DEFAULT_RANGE;
+  const admin = adminMounts()[0];
+  const runs = admin?.resources.find((resource) => resource.name === JOB_ENTITY.jobs);
+  const workers = admin?.resources.find((resource) => resource.name === JOB_ENTITY.workers);
+  const json = `${tabPath}?json=1`;
+  const data = await overviewData(range, Date.now());
+  // The framework catalog's locale for every label, whatever the app's default is.
+  return runWithContext(createContext({ locale: 'en', tz: 'UTC' }), () =>
+    renderToHtml(
+      <JobsOverview
+        data={data}
+        range={range}
+        locale="en"
+        timeZone="UTC"
+        hrefs={{
+          state: (state) =>
+            admin === undefined || runs === undefined
+              ? json
+              : listHref(admin.basePath, runs, { scope: state }),
+          name: (name) =>
+            admin === undefined || runs === undefined
+              ? json
+              : listHref(admin.basePath, runs, {
+                  filters: [{ field: 'name', op: 'eq', value: name }],
+                }),
+          workers:
+            admin === undefined || workers === undefined ? json : listHref(admin.basePath, workers),
+          range: (next) => `${tabPath}?${RANGE_PARAM}=${next}`,
+        }}
+      />,
+    ),
+  );
+}

package/src/jobs/overview.tsx

@@ -0,0 +1,189 @@
+// `/admin/jobs` — the overview: depth tiles from one `stats()`, done-vs-failed over a chosen range,
+// and per job name its volume, failure rate and mean duration. A plain read with a declared refresh
+// (`<meta http-equiv="refresh">`): no socket, no script, the admin's zero-JS rule kept.
+
+import { t } from '@ultimat3/i18n';
+import { BarChart, Card, DataTable, Link, StatTile } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import type { AdminApp, AdminRoute } from '../admin';
+import styles from '../admin.module.scss';
+import { listHref } from '../list-request';
+import { type AdminScreen, guardedScreen, widgetContextOf } from '../screen-frame';
+import { JOB_ENTITY } from './job-entities';
+import {
+  type NameRow,
+  OVERVIEW_RANGES,
+  type OverviewData,
+  type OverviewRange,
+  overviewData,
+  RANGE_PARAM,
+  rangeOf,
+} from './overview-data';
+
+/** Seconds between the browser's own re-reads of the overview. A measurement, not a live feed. */
+export const OVERVIEW_REFRESH_SECONDS = 30;
+
+const TILE_STATES = ['ready', 'running', 'delayed', 'suspended', 'dead'] as const;
+
+export interface JobsOverviewProps {
+  readonly data: OverviewData;
+  readonly range: OverviewRange;
+  readonly locale: string;
+  readonly timeZone: string;
+  /** The runs list in one state, the workers list, the overview at a range: links, never calls. */
+  readonly hrefs: {
+    readonly state: (state: string) => string;
+    readonly name: (name: string) => string;
+    readonly workers: string;
+    readonly range: (range: OverviewRange) => string;
+  };
+}
+
+/** What the overview draws, from data alone — the `/_x` jobs tab renders this same component. */
+export function JobsOverview(props: JobsOverviewProps): JSX.Element {
+  const count = new Intl.NumberFormat(props.locale);
+  const percent = new Intl.NumberFormat(props.locale, {
+    style: 'percent',
+    maximumFractionDigits: 1,
+  });
+  const bucket = new Intl.DateTimeFormat(props.locale, {
+    timeZone: props.timeZone,
+    ...(OVERVIEW_RANGES[props.range].ms > 86_400_000
+      ? { month: 'short', day: 'numeric' }
+      : { hour: '2-digit', minute: '2-digit' }),
+  });
+  const tile = (key: string, value: string, href: string): JSX.Element => (
+    <li>
+      <a href={href}>
+        <StatTile label={t(`admin.jobs.tile.${key}`)} value={value} stat={key} />
+      </a>
+    </li>
+  );
+  const columns = [
+    {
+      key: 'name',
+      header: t('admin.jobs.byName.name'),
+      cell: (row: NameRow) => <Link href={props.hrefs.name(row.name)}>{row.name}</Link>,
+    },
+    {
+      key: 'volume',
+      header: t('admin.jobs.byName.volume'),
+      numeric: true,
+      cell: (row: NameRow) => <span>{count.format(row.volume)}</span>,
+    },
+    {
+      key: 'failureRate',
+      header: t('admin.jobs.byName.failureRate'),
+      numeric: true,
+      cell: (row: NameRow) => (
+        <span>
+          {row.failureRate === null ? t('admin.value.empty') : percent.format(row.failureRate)}
+        </span>
+      ),
+    },
+    {
+      key: 'meanMs',
+      header: t('admin.jobs.byName.meanMs'),
+      numeric: true,
+      cell: (row: NameRow) => (
+        <span>
+          {row.meanMs === null
+            ? t('admin.value.empty')
+            : t('admin.jobs.ms', { ms: count.format(Math.round(row.meanMs)) })}
+        </span>
+      ),
+    },
+  ];
+  return (
+    <>
+      <ul class={styles['tiles']}>
+        {TILE_STATES.map((state) =>
+          tile(state, count.format(props.data.totals[state]), props.hrefs.state(state)),
+        )}
+        {tile('workers', count.format(props.data.workers), props.hrefs.workers)}
+        {tile(
+          'oldestReady',
+          t('admin.jobs.seconds', {
+            seconds: count.format(Math.round(props.data.oldestReadyMs / 1000)),
+          }),
+          props.hrefs.state('ready'),
+        )}
+      </ul>
+      <nav aria-label={t('admin.jobs.range.label')}>
+        <ul class={styles['scopes']}>
+          {(Object.keys(OVERVIEW_RANGES) as OverviewRange[]).map((range) => (
+            <li>
+              <Link
+                href={props.hrefs.range(range)}
+                {...(range === props.range ? { 'aria-current': 'page' } : {})}
+              >
+                {t(`admin.jobs.range.${range}`)}
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </nav>
+      <Card header={<h2>{t('admin.jobs.chart.title')}</h2>}>
+        <BarChart
+          label={t('admin.jobs.chart.label', { range: t(`admin.jobs.range.${props.range}`) })}
+          points={props.data.bars.map((bar) => ({
+            key: bucket.format(new Date(bar.startMs)),
+            value: bar.done,
+            secondary: bar.failed,
+          }))}
+          seriesLabels={{
+            primary: t('admin.jobs.chart.done'),
+            secondary: t('admin.jobs.chart.failed'),
+          }}
+        />
+      </Card>
+      <DataTable
+        caption={t('admin.jobs.byName.caption')}
+        columns={columns}
+        rows={props.data.names}
+        rowKey={(row) => row.name}
+        emptyTitle={t('admin.jobs.byName.empty')}
+      />
+    </>
+  );
+}
+
+/** The overview screen: decided by the route's own pair (`admin:read` + `job:read`) first. */
+export function jobsOverviewScreen(app: AdminApp, route: AdminRoute): AdminScreen {
+  return guardedScreen(app, route, async (request) => {
+    const runs = app.resource(JOB_ENTITY.jobs);
+    const refresh = <meta http-equiv="refresh" content={String(OVERVIEW_REFRESH_SECONDS)} />;
+    // The fleet's numbers are every tenant's: an org-scoped operator is sent to their own rows.
+    if (request.ctx.actor.orgId !== undefined) {
+      return (
+        <p class={styles['note']}>
+          {t('admin.jobs.scoped')}{' '}
+          <Link href={listHref(app.basePath, runs)}>{t(runs.titleKey)}</Link>
+        </p>
+      );
+    }
+    const url = new URL(request.url);
+    // An unknown `?range=` is refused by name — the frame answers it 400, as a list's filter is.
+    const range = rangeOf(url);
+    const ctx = widgetContextOf(app, request.ctx);
+    const data = await overviewData(range, Date.now());
+    return (
+      <>
+        {refresh}
+        <JobsOverview
+          data={data}
+          range={range}
+          locale={ctx.locale}
+          timeZone={ctx.timeZone}
+          hrefs={{
+            state: (state) => listHref(app.basePath, runs, { scope: state }),
+            name: (name) =>
+              listHref(app.basePath, runs, { filters: [{ field: 'name', op: 'eq', value: name }] }),
+            workers: listHref(app.basePath, app.resource(JOB_ENTITY.workers)),
+            range: (next) => `${url.pathname}?${RANGE_PARAM}=${next}`,
+          }}
+        />
+      </>
+    );
+  });
+}

package/src/json-text.ts

@@ -0,0 +1,52 @@
+// A value as the JSON an operator READS: keys sorted so two equal values read alike, a bigint as
+// its digits, an instant as ISO text. Total — `JSON.stringify` throws on a bigint, and a `money()`
+// column puts one on the row. Never a hash form: `@ultimat3/core`'s `canonicalJson` spells a
+// bigint `BigInt(2)` so two types cannot collide, which is right for a key and wrong for a screen.
+
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+function text(value: unknown, seen: ReadonlySet<unknown>): string {
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value);
+    case 'number':
+      return Number.isFinite(value) ? String(value) : 'null';
+    case 'boolean':
+      return String(value);
+    case 'bigint':
+      return value.toString();
+    case 'object':
+      break;
+    default:
+      return 'null';
+  }
+  if (value === null) return 'null';
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? 'null' : JSON.stringify(value.toISOString());
+  }
+  // A cycle has no JSON; the second visit is where it is cut, and it says so.
+  if (seen.has(value)) return '"[circular]"';
+  const inside = new Set(seen).add(value);
+  if (Array.isArray(value)) return `[${value.map((one) => text(one, inside)).join(',')}]`;
+  if (value instanceof Set) return text([...value], inside);
+  const entries: readonly (readonly [string, unknown])[] =
+    value instanceof Map
+      ? [...value].map(([key, held]) => [String(key), held] as const)
+      : Object.entries(value);
+  return `{${[...entries]
+    .filter(([, held]) => held !== undefined)
+    .sort(([a], [b]) => byCodeUnit(a, b))
+    .map(([key, held]) => `${JSON.stringify(key)}:${text(held, inside)}`)
+    .join(',')}}`;
+}
+
+/** `value` as deterministic, readable JSON text. */
+export function jsonText(value: unknown): string {
+  return text(value, new Set());
+}
+
+/** One value as a line of an audit diff or a detail row: text as it is, anything else as JSON. */
+export function valueText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  return typeof value === 'string' ? value : jsonText(value);
+}