@ultimat3/admin 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -11,10 +11,11 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **The MCP caller is the ambient actor for the whole call, tenant included.** `mcp.ts` wraps `callAdminTool` in a child context (a fresh root one over stdio); `resolveToken` and `adminActorOf` both carry `orgId`. Pinned in `mcp-context.test.ts`, `mcp-tenant.test.ts`.
 - **`defineAdmin({ entities, db })` is a served admin; a host writes nothing.** `routes.ts` gives EVERY route a screen (`screens.ts` — a `Record<AdminView, …>`, so a new view cannot mount with nothing behind it) and `AdminRouteConfig.respond(request)` is the only way in: GET or a posted form in, `{ status, body }` or a 303 out. `repo-entity.ts` is the ONE adapter from the typed handle to `AdminRepo`; it adds no predicate (tenancy, soft delete, sealing and invariants are the handle's) and never spreads a row. A resource with neither a table in `db` nor a `repo:` is `X_ADMIN_REPO_UNBOUND` at `defineAdmin`. Pinned in `mounted-screens.test.ts`, `repo-entity.test.ts`, `admin-bind.test.ts`.
 - **A screen's guard is composed, never written.** A resource screen asks `crud.ts` FIRST and renders what it answered — only it holds the row a row-level rule reads. Every other screen (a `pages:` entry, dashboard, jobs, audit, search) is built through `guardedScreen()` (`screen-frame.tsx`): `decideAll` over the route's permissions, the refusal audited (`auditRefusal`), answered 403. `pages.ts` composes `[admin:read, …declared]`; `AdminPageProps.ctx` is required by the type; an empty permission list is `X_ADMIN_PAGE_UNGUARDED` at `defineAdmin`.
-- **No screen ships a script; an app file that CLAIMED its route may** (`claimAdminRoute`: a `pages:` entry or the dashboard; `load` = `screenFor`, `frame: 'none'`). Only a config `claims.ts` issued for that path passes `claimable`, else `X_ROUTE_DUPLICATE`. Every admin route is `ssr` + `hydrate: 'never'`, so a control is a link or a native form: `<Pagination hrefFor>`, `<DataTable sortHrefFor>`, scope tabs as links, the filter bar one GET form, a form posted at the URL that rendered it, an action posted at its ROW's URL (`_operation`). `form-decode.ts` is the one place posted strings become typed input, per widget — an empty box of a typed widget (money, number, instant, JSON) is `null`, never `''`.
+- **No screen ships a script; an app file that CLAIMED its route may** (`claimAdminRoute`: a `pages:` entry or the dashboard; `load` = `screenFor`, `frame: 'none'`). Only a config `claims.ts` issued for that path passes `claimable`, else `X_ROUTE_DUPLICATE`. Every admin route is `ssr` + `hydrate: 'never'`, so a control is a link or a native form ([which](../../docs/history/admin.md#moved-out-2026-11-03-plan-101-wave-3-the-claudemd-ceiling)).
 - **A list's state is its URL, and a parameter the resource does not derive is REFUSED.** `list-request.ts` is the one parser and builder — `?cursor=`, `?sort=<field>:<asc|desc>`, `?scope=<name>` (`*` = none, not even the default; undeclarable), `?f.<field>[.<op>]=<value>` (repeat for `in`; empty = absent). `list-filters.ts` owns the operators per filter shape and the ONE validator (`checkedFilter`) the URL and the MCP list tool's `where` both pass. Unknown field, operator, sort, scope or parameter, or a value that is not the column's type: `X_ADMIN_FILTER_INVALID`, a 400 naming what the list answers — never the unfiltered list.
+- **The audit trail's state is its URL, and a parameter it does not read is REFUSED.** `audit-request.ts` is the one parser and builder (`?entity= ?actor= ?outcome= ?since= ?until= ?changes=1 ?before=`); `orgId` is the actor's, so `?org=` is a 400. The screen re-checks each entry with `auditEntryMatches`: a custom log that ignores a field narrows a page, never widens it. Audit diffs mask `maskedFieldsOf(resource)` (`detail.tsx`). Store parity: `audit-query-fixture.ts`.
 - **One composition of predicates** (`list-scope.ts`): row scope (`rows`), then scope, then filters. Every read of a resource builds its `where` there, and every read of ONE row is `findRow` — never `repo.find` from a screen, `crud.ts` or `mcp.ts` — so a row outside `rows(actor)` is "not found" on list, search, detail, edit, action, lookup, labels and MCP alike (`row-scope.test.ts`). App-declared predicates (`scopes`, `rows`) pass `declaredFilters`: any column, never a sealed one.
-- **A widget never reads a row.** What a page shows of the resources it references is read ONCE per target by `relations.ts` (`relationDataFor`: one statement, two for a picked target over `LOOKUP_SELECT_MAX`) and handed down as `WidgetContext.labelFor` / `optionsFor` / `lookupHref`. A target the actor may not list is an id with no name. `list-relations.test.ts` asserts the statement count at the driver. The picker is server-rendered: a `<select>` for a small target, else an id box + the target's lookup screen (`/admin/<resource>/lookup`, `screen-lookup.tsx`, `return` held to the admin's own paths).
+- **A widget never reads a row.** What a page shows of the resources it references is read ONCE per target by `relations.ts` (`relationDataFor`: one statement, two for a picked target over `LOOKUP_SELECT_MAX`) and handed down as `WidgetContext.labelFor` / `optionsFor` / `lookupHref`. A target the actor may not list is an id with no name. `list-relations.test.ts` asserts the statement count at the driver.
 - **A sealed column is never a filter, a scope or row-scope predicate, a label, a lookup key or a computed column's input** — `.sealed({ lookup: true })` included: a filter value rides a URL, and a URL is logged. `computedRow` drops sealed names from the row a column's `value` is handed.
 - **The tenant column is the handle's, never an input** (`crud-input.ts`): not a form field, a list column or a filter; a create is stamped with the ACTOR's tenant and a patch never carries the column.
 - **Computed columns are a closed renderer set** (`renderers.tsx`: `badge`, `relative-time`, `money`, `truncate`, `link`, `json`) or a component; `AdminComputedColumn` is typed over `AdminRow` so a resource stays covariant in `Row`.
@@ -59,17 +60,17 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **A job-store predicate the store cannot answer is refused by name** (`job-where.ts`, `X_ADMIN_FILTER_INVALID`): one order (`createdAt desc`), equality on state/queue/name/tenant, an id PREFIX for the id box. `listScreen` answers a repo's refusal 400, as the URL's. "All matching" over jobs is `AdminAction.matching` onto the store's bulk verbs, never a walk.
 - **A resource's permissions are named after its `permission` noun** (`resource.permission`, default the entity name) — every `permissionsForOperation` site reads it, never `resource.name`.
 - **An action's admin gate is ONE function** (`adminPermissionForAction`, `action-gate.ts`): `destructive` → `admin:destroy`; `matching` → `admin:write`, `readonly` beside it or not — it changes every row the list matches; `readonly` → `admin:read`; else `admin:write`. A contradiction fails closed. The same value is its MCP tool's `scope`. `action-gate.test.ts`.
-- **Every admin MCP tool carries ONE scope** — `admin:read`, `admin:write` or `admin:destroy`, by what it does (`mcp-tools.ts`); `adminToolScopes` hands that cut to `defineAppMcp({ scopes })`. A token's own scopes are `AdminMcpActor.tokenScopes` (not `scopes`: core's `Actor.scopes` is another thing), expanded `destroy ⇒ write ⇒ read` by `adminTokenScopes` (`mcp-scopes.ts`). **Unstated = full strength** (the actor's); **`[]` = granted nothing**, every tool refused `X_MCP_SCOPE_DENIED`; a non-admin scope is dropped. The scope gate runs before the actor's policy, which still decides. `mcp-scopes.test.ts`.
+- **Every admin MCP tool carries ONE scope** — `admin:read`, `admin:write` or `admin:destroy`, by what it does (`mcp-tools.ts`); `adminToolScopes` hands that cut to `defineAppMcp({ scopes })`. **Unstated = full strength** (the actor's); **`[]` = granted nothing**, every tool refused `X_MCP_SCOPE_DENIED`; a non-admin scope is dropped. The scope gate runs before the actor's policy, which still decides. `mcp-scopes.test.ts`.
 - **The `/admin` home counts only what opted in** — `count: true` on the resource (`screen-home-counts.ts`): one `count()` over `rowWhere(actor)` per visit, so it is never a default. Only resources the actor may list; a repo with no `count()`, or one that throws, has no tile — never a zero.
 - **`matching` is "all matching" as ONE call** (`batch-matching.ts`): the list's `where`, gated by the batch's grant, confirmed as `<entity>:all matching`, audited once (`admin.batch.matching`). A checked selection never reaches it.
 - **An action on a row the actor cannot see is refused, `when` or none** (`actionApplies`: a `null` row is no row).
 - **An action's input field is labelled `admin.input.<action>.<field>`** — never under `admin.action.<action>`, which is a leaf: a JSON catalog cannot hold both.
-- **`x_admin_audit`'s DDL is the leaf `audit-schema.ts`** (`@ultimat3/admin/schema`): the boot applies it in every role; `serve-graph.test.ts` exempts exactly that file.
+- **`./schema` (`audit-schema.ts` + `error-groups-schema.ts`) is the DDL leaf**, exempt in `serve-graph.test.ts`. **`./error-groups`**: sink + stores, no screen, off the barrel.
 - Money via `assertMoney`, timestamps via `assertZone`, pagination via `pagination.ts`. No `offset`, ever.
 - **One cursor codec.** `pagination.ts` is the only file calling core's `encodeCursor`/`decodeCursor`; it wraps them as `encodeAdminCursor`/`decodeAdminCursor`, scoped `admin:<resource>`. An invalid cursor is page one here, not an error page — but the signature is checked first, so a forged one cannot seek.
 - Labels are i18n keys derived in `resource.ts` (`admin.<entity>.field.<name>`); only `.tsx` calls `t()`. An action's is `actionLabelKey` (`action-label.ts`), never respelled. `AdminApp.catalogKeys()` (`catalog-keys.ts`) is every derived key — the CLI's `i18n` step audits exactly that list. MCP tool descriptions are literal English (protocol payload, not UI copy).
 - Colours only via `ThemeTokenRef` (`--x-*`). Raw hex does not typecheck.
-- **One owner of `globalThis.React` is `@ultimat3/ui`'s** (`probe`/`unprobe`); `inert-jsx.ts` keeps only the walkers. `inert-jsx.test.ts` drives both install orders.
+- **The walker is `@ultimat3/core/render-nodes`**: `nodesOf(…, { components: 'keep' })` reads the props a view handed a ui component; `'stop'` keeps ui's internals out. `inert-jsx-fixture.ts` keeps only `h`, `renderHtml`, `renderComponent`; `inert-jsx.test.ts` holds them.
 - **A `/_x` panel orders by CODE UNIT, never `localeCompare`**; **the locale picker reads `registeredLocales()`**, never a bundled list.
 - Views are pure functions of props: no `createSignal`, local state or event handler.
 - **No test reaches a `.tsx` statically**: `await import('@ultimat3/render/server')`, then `await import('./routes')`.
@@ -93,7 +94,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `action-row.ts` / `action-input.ts` / `action-form.tsx` / `screen-action.tsx` | one action on one row / input schema ⇄ form fields / the action's form / row-action and batch writes |
 | `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` | the log interface + memory log / the Postgres log / readable JSON for a cell or a diff |
+| `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 |
 | `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 |

package/README.md

@@ -2,6 +2,17 @@
 
 **Two dashboards live here. They are not the same thing — and they have two doors.**
 
+`bun add @ultimat3/admin` · guide: [Admin Dashboard](https://github.com/developerz-ai/ultimate/wiki/Admin-Dashboard)
+
+```ts
+import { staticAuthz } from '@ultimat3/admin';
+import { defaultDevSources, devDashboard } from '@ultimat3/admin/dev';
+
+const authz = staticAuthz(['admin:read']);
+const actors = [{ id: 'dev-admin', roles: ['admin'] }];
+export const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // /_x
+```
+
 | | `/_x` — framework dev dashboard | `admin` — generated app admin |
 |---|---|---|
 | Import | `@ultimat3/admin/dev` | `@ultimat3/admin` |
@@ -22,7 +33,7 @@ One panel per file. Each kills one question, and each is available as `--json`
 | `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) |
-| `mail` | caught mail, rendered, per locale, with the locale gaps listed |
+| `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 |
 | `manifest` | emitted `x.manifest.json` diffed against the committed one |
@@ -272,7 +283,30 @@ table only as `[redacted]` — `@ultimat3/core`'s `REDACTED`, the logger's marke
 table is applied at boot with every other framework table (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`),
 from the leaf module `@ultimat3/admin/schema` (`SQL_ADMIN_AUDIT_TABLE`, `ADMIN_AUDIT_TABLE`) —
 no migration, no screen loaded to install it. That subpath is their one import path: 25.0.0 took
-them off the barrel.
+them off the barrel. `x_error_groups` (`SQL_ERROR_GROUPS_TABLE`, `ERROR_GROUPS_TABLE`) rides the
+same subpath.
+
+**Error groups** (`As of 2026-11`). `@ultimat3/admin/error-groups` is the sink and its stores, and
+nothing else, because every role installs it: `errorGroupsSink({ store, onNewGroup?, ignore?,
+perMinute? })` is an `ErrorReporter` folding each report into its `errorFingerprint` group —
+outside the request's transaction, capped per minute, `onNewGroup` (a job handle) enqueued once
+per new group fleet-wide (`xmax = 0`). Install it beside any other reporter with core's
+`chainErrorReporters`. Stores: `postgresErrorGroupsStore()`, `memoryErrorGroupsStore()`;
+retention `errorGroupsPurgeTarget(store, { olderThanMs })`. The screens are the barrel's:
+`pages: errorGroupsPages({ store, navGroup? })` mounts `/admin/errors` behind `errors:read`
+(`ERRORS_READ`).
+
+`/admin/audit` is the whole trail, 100 entries per page, newest first, behind one native GET form:
+`?entity=`, `?actor=`, `?outcome=`, `?since=`, `?until=` (an instant with an offset or `Z`, a
+bare `YYYY-MM-DD` as that day's first UTC instant, or the form's `YYYY-MM-DDTHH:mm`, given its
+`Z` by `utcFormInstantOf` and nowhere else; `until` is exclusive), `?changes=1`, and the
+keyset `?before=`, which the older link writes with the filters kept. `auditRequestOf(url)`
+is the one parser and `auditHref(path, request)` the one builder; a parameter it does not
+read (`?org=` too: the tenant is the actor's) is `X_ADMIN_FILTER_INVALID`, a 400. Both stores
+take `outcome`, `since` and `until` (`AuditQuery`). An app's own log should too: the screen
+re-checks every entry it returns with `auditEntryMatches`, so a log that ignores a field draws
+a short page, never another tenant's or another outcome's entry. A diff on either screen
+masks a `sensitive` or sealed field's value, whatever the stored entry holds.
 
 ### A sealed column
 

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/admin",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "admin",
+    "dashboard",
+    "crud",
+    "mcp"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Admin-Dashboard",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -16,7 +26,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./dev": "./src/dev/index.ts",
-    "./schema": "./src/audit-schema.ts"
+    "./schema": "./src/audit-schema.ts",
+    "./error-groups": "./src/error-groups.ts"
   },
   "files": [
     "src",
@@ -34,21 +45,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "29.3.2",
-    "@ultimat3/ai": "29.3.2",
-    "@ultimat3/cache": "29.3.2",
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/db": "29.3.2",
-    "@ultimat3/entity": "29.3.2",
-    "@ultimat3/http": "29.3.2",
-    "@ultimat3/i18n": "29.3.2",
-    "@ultimat3/jobs": "29.3.2",
-    "@ultimat3/mcp": "29.3.2",
-    "@ultimat3/money": "29.3.2",
-    "@ultimat3/policy": "29.3.2",
-    "@ultimat3/query": "29.3.2",
-    "@ultimat3/render": "29.3.2",
-    "@ultimat3/schema": "29.3.2",
-    "@ultimat3/ui": "29.3.2"
+    "@ultimat3/action": "30.0.0",
+    "@ultimat3/ai": "30.0.0",
+    "@ultimat3/cache": "30.0.0",
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/db": "30.0.0",
+    "@ultimat3/entity": "30.0.0",
+    "@ultimat3/http": "30.0.0",
+    "@ultimat3/i18n": "30.0.0",
+    "@ultimat3/jobs": "30.0.0",
+    "@ultimat3/mcp": "30.0.0",
+    "@ultimat3/money": "30.0.0",
+    "@ultimat3/policy": "30.0.0",
+    "@ultimat3/query": "30.0.0",
+    "@ultimat3/render": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/ui": "30.0.0"
   }
 }

package/src/audit-pg.ts

@@ -15,6 +15,7 @@ import {
   type AuditSink,
   auditEntry,
   auditLimit,
+  auditWindow,
   isAllowedRead,
 } from './audit';
 import { ADMIN_AUDIT_TABLE } from './audit-schema';
@@ -105,6 +106,10 @@ function selectFor(query: AuditQuery, limit: number): { text: string; values: un
   if (query.entityId !== undefined) where.push(`entity_id = ${bind(query.entityId)}`);
   if (query.actorId !== undefined) where.push(`actor_id = ${bind(query.actorId)}`);
   if (query.orgId !== undefined) where.push(`org_id = ${bind(query.orgId)}`);
+  if (query.outcome !== undefined) where.push(`outcome = ${bind(query.outcome)}`);
+  // Normalised by `auditWindow` before this runs: an ISO instant, never a bare local time.
+  if (query.since !== undefined) where.push(`at >= ${bind(query.since)}::timestamptz`);
+  if (query.until !== undefined) where.push(`at < ${bind(query.until)}::timestamptz`);
   if (query.before !== undefined) {
     where.push(
       `(at, id) < (${bind(query.before.at)}::timestamptz, ${bind(query.before.id)}::uuid)`,
@@ -187,7 +192,8 @@ export function postgresAuditLog(options: PostgresAuditLogOptions = {}): AuditLo
       for (const sink of sinks) await sink.write(entry);
       return entry;
     },
-    async entries(query = {}): Promise<readonly AuditEntry[]> {
+    async entries(asked = {}): Promise<readonly AuditEntry[]> {
+      const query = auditWindow(SUBJECT, asked);
       const select = selectFor(query, auditLimit(SUBJECT, query));
       const rows = await client().query<AuditRow>(select);
       return rows.map(entryOf);

package/src/audit-request.ts

@@ -0,0 +1,129 @@
+// URL ⇄ the slice of the audit trail `/admin/audit` is asked for. The screen's whole state lives in
+// its query string, as a list's does (`list-request.ts`): the filter form is a native GET and the
+// older link is a URL. One parser and one builder, so the two cannot disagree about a name. A
+// parameter the screen does not answer is REFUSED — never the unfiltered trail.
+//
+//   ?entity=<name>  ?actor=<id>  ?outcome=<allowed|denied|failed>  ?changes=1
+//   ?since=<instant>  ?until=<instant>   ISO-8601 with an offset, YYYY-MM-DD as UTC, or the
+//                                        form's YYYY-MM-DDTHH:mm, given the Z its UTC label states
+//   ?before=<at>~<id>                    keyset: the entry the previous page ended on
+//
+// An EMPTY value is no parameter at all: a GET form submits every input it holds. `orgId` is
+// never a parameter — it is the actor's (`screen-system.tsx`), so `?org=` is unknown and a 400.
+
+import type { AuditCursor, AuditOutcome, AuditQuery } from './audit';
+import { AdminFilterInvalidError } from './errors';
+import { utcFormInstantOf } from './list-filters';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The query parameter an older page of a row's history is asked for by: `?history=<at>~<id>`. */
+export const HISTORY_PARAM = 'history';
+
+/** The cursor as one parameter value — an ISO instant holds no `~`, a uuid neither. */
+export const historyCursorText = (cursor: AuditCursor): string => `${cursor.at}~${cursor.id}`;
+
+/** A posted-back cursor, or `undefined` for anything that is not one: page one, never an error. */
+export function historyCursorOf(raw: string | null): AuditCursor | undefined {
+  if (raw === null) return undefined;
+  const at = raw.indexOf('~');
+  if (at <= 0) return undefined;
+  const instant = raw.slice(0, at);
+  const id = raw.slice(at + 1);
+  // A uuid, because the durable log compares it as one: anything else would be a cast error from
+  // the database where a hand-edited URL deserves page one.
+  return Number.isNaN(Date.parse(instant)) || !UUID.test(id) ? undefined : { at: instant, id };
+}
+
+export const AUDIT_OUTCOMES: readonly AuditOutcome[] = ['allowed', 'denied', 'failed'];
+
+/** The parameter names, in the order the builder writes them. */
+export const AUDIT_PARAMS = [
+  'entity',
+  'actor',
+  'outcome',
+  'since',
+  'until',
+  'changes',
+  'before',
+] as const;
+
+/**
+ * The refusal's fix: a URL at the screen's own path (`basePath` included) that it answers, with
+ * every parameter it reads named beside it.
+ */
+export const auditUrlFix = (path: string): string =>
+  `${path}?outcome=denied&since=2026-11-01   # keep only entity, actor, outcome (allowed|denied|failed), since, until (YYYY-MM-DD or ISO-8601 with an offset), changes=1, before; drop every other parameter`;
+
+type AuditParam = (typeof AUDIT_PARAMS)[number];
+
+/** What a URL may ask of the trail: `AuditQuery` minus the actor's tenant and the page size. */
+export type AuditRequest = Pick<
+  AuditQuery,
+  'entity' | 'actorId' | 'outcome' | 'since' | 'until' | 'changes' | 'before'
+>;
+
+const isParam = (key: string): key is AuditParam =>
+  (AUDIT_PARAMS as readonly string[]).includes(key);
+
+/** The trail a URL asks for. Throws `X_ADMIN_FILTER_INVALID` for anything it cannot read. */
+export function auditRequestOf(url: URL): AuditRequest {
+  const refuse = (asked: string, cause: string): never => {
+    throw new AdminFilterInvalidError({
+      entity: url.pathname,
+      asked,
+      cause,
+      known: AUDIT_PARAMS.map((name) => `${name}=`),
+      fix: auditUrlFix(url.pathname),
+    });
+  };
+  const out: { -readonly [K in keyof AuditRequest]: AuditRequest[K] } = {};
+  for (const key of new Set(url.searchParams.keys())) {
+    const values = url.searchParams.getAll(key).filter((value) => value !== '');
+    const last = values[values.length - 1];
+    if (!isParam(key)) refuse(key, 'is not a parameter the audit trail reads');
+    if (last === undefined) continue;
+    const asked = `${key}=${last}`;
+    switch (key) {
+      case 'entity':
+        out.entity = last;
+        break;
+      case 'actor':
+        out.actorId = last;
+        break;
+      case 'outcome':
+        out.outcome =
+          AUDIT_OUTCOMES.find((known) => known === last) ??
+          refuse(asked, `is not an outcome (${AUDIT_OUTCOMES.join(', ')})`);
+        break;
+      case 'since':
+      case 'until':
+        out[key] =
+          utcFormInstantOf(last) ??
+          refuse(asked, 'is neither an ISO-8601 instant with an offset nor a YYYY-MM-DD date');
+        break;
+      case 'changes':
+        out.changes = last === '1' || refuse(asked, 'takes 1, or is left out');
+        break;
+      case 'before':
+        out.before =
+          historyCursorOf(last) ?? refuse(asked, 'is not a position this trail wrote (<at>~<id>)');
+        break;
+    }
+  }
+  return out;
+}
+
+/** The URL of one slice of the trail, rooted at the screen's own path. */
+export function auditHref(path: string, request: AuditRequest): string {
+  const query = new URLSearchParams();
+  if (request.entity !== undefined) query.set('entity', request.entity);
+  if (request.actorId !== undefined) query.set('actor', request.actorId);
+  if (request.outcome !== undefined) query.set('outcome', request.outcome);
+  if (request.since !== undefined) query.set('since', request.since);
+  if (request.until !== undefined) query.set('until', request.until);
+  if (request.changes === true) query.set('changes', '1');
+  if (request.before !== undefined) query.set('before', historyCursorText(request.before));
+  const search = query.toString();
+  return search === '' ? path : `${path}?${search}`;
+}

package/src/audit-schema.ts

@@ -1,6 +1,10 @@
-// The DDL of the admin's one framework table, and nothing else: a LEAF module, so the boot's
-// `FRAMEWORK_SCHEMA` (`@ultimat3/cli`) can apply it in every role through `@ultimat3/admin/schema`
-// without pulling one screen, one view or one stylesheet into a worker's module graph.
+// The DDL of the admin's framework tables, and nothing else: a LEAF module, so the boot's
+// `FRAMEWORK_SCHEMA` (`@ultimat3/cli`) can apply them in every role through `@ultimat3/admin/schema`
+// without pulling one screen, one view or one stylesheet into a worker's module graph. The audit
+// table is declared here; the error-groups table beside it, in its own leaf, re-exported below.
+
+/** `x_error_groups` — one subpath for every admin table the boot applies, one import line there. */
+export { ERROR_GROUPS_TABLE, SQL_ERROR_GROUPS_TABLE } from './error-groups-schema';
 
 /** The table. One name, read by this DDL and by `audit-pg.ts`'s insert and select. */
 export const ADMIN_AUDIT_TABLE = 'x_admin_audit';

package/src/audit.ts

@@ -4,6 +4,8 @@
 
 import { canonicalJson, finiteCount, REDACTED } from '@ultimat3/core';
 import type { AdminActor, AdminDecision } from './authz';
+import { AdminFilterInvalidError } from './errors';
+import { instantOf } from './list-filters';
 import type { AdminRow } from './registry';
 
 /** Named once, so both refusals below say the same thing about the same call. */
@@ -79,6 +81,15 @@ export interface AuditQuery {
    * changed something or was refused. What a row's history shows.
    */
   readonly changes?: boolean;
+  /** Only entries with this outcome: what was refused is `denied`, what threw is `failed`. */
+  readonly outcome?: AuditOutcome;
+  /**
+   * Only entries at or after this instant: ISO-8601 with an offset, or a bare `YYYY-MM-DD` as that
+   * day's first instant in UTC. Anything else is `X_ADMIN_FILTER_INVALID` — no store invents a zone.
+   */
+  readonly since?: string;
+  /** Only entries strictly BEFORE this instant — exclusive, so two windows never share an entry. */
+  readonly until?: string;
 }
 
 export interface AuditLog {
@@ -86,6 +97,9 @@ export interface AuditLog {
   /**
    * Newest first, at most `limit` (`AUDIT_PAGE_MAX` at the outside). A copy — the log cannot be
    * mutated through what it hands out. Async because the record is a table, not this process.
+   * A log of an app's own must honour EVERY field of `AuditQuery`: `/admin/audit` re-checks each
+   * returned entry against the query (`auditEntryMatches`) and drops what does not match, so a log
+   * that ignores `outcome` or a bound draws a short page — never an unfiltered one.
    */
   entries(query?: AuditQuery): Promise<readonly AuditEntry[]>;
   /**
@@ -133,6 +147,50 @@ export const auditLimit = (subject: string, query: AuditQuery): number =>
         finiteCount(subject, 'entries limit', query.limit),
   );
 
+/** The store refusal's fix: the two spellings a bound in `AuditQuery` may take. */
+export const AUDIT_BOUND_FIX =
+  "entries({ since: '2026-11-01', until: '2026-11-02T00:00:00+02:00' })   # a bound is YYYY-MM-DD (UTC) or ISO-8601 with an offset";
+
+/** One bound, as the ISO instant a store compares — or refused, naming the grammar it takes. */
+const boundOf = (subject: string, name: 'since' | 'until', raw: string): string => {
+  const at = instantOf(raw);
+  if (at !== undefined) return at;
+  throw new AdminFilterInvalidError({
+    entity: subject,
+    asked: `${name}=${raw}`,
+    cause: 'is neither an ISO-8601 instant with an offset nor a YYYY-MM-DD date (read as UTC)',
+    known: ['since=2026-11-01', 'until=2026-11-01T12:00:00Z'],
+    fix: AUDIT_BOUND_FIX,
+  });
+};
+
+/**
+ * A query with its bounds normalised to ISO instants, or refused. Every store calls it before it
+ * reads, so a bound no store can read is an error in both — never "no bound" in one of them.
+ */
+export function auditWindow(subject: string, query: AuditQuery): AuditQuery {
+  return {
+    ...query,
+    ...(query.since === undefined ? {} : { since: boundOf(subject, 'since', query.since) }),
+    ...(query.until === undefined ? {} : { until: boundOf(subject, 'until', query.until) }),
+  };
+}
+
+/**
+ * Whether one entry answers a query, `before` and `limit` aside — the memory log's filter, and the
+ * check `/admin/audit` runs again on whatever a log of an app's own returned. A bound that does not
+ * parse matches nothing: this predicate fails closed.
+ */
+export const auditEntryMatches = (entry: AuditEntry, query: AuditQuery): boolean =>
+  (query.entity === undefined || entry.entity === query.entity) &&
+  (query.entityId === undefined || entry.entityId === query.entityId) &&
+  (query.actorId === undefined || entry.actor.id === query.actorId) &&
+  (query.orgId === undefined || entry.actor.orgId === query.orgId) &&
+  (query.outcome === undefined || entry.outcome === query.outcome) &&
+  (query.since === undefined || Date.parse(entry.at) >= Date.parse(query.since)) &&
+  (query.until === undefined || Date.parse(entry.at) < Date.parse(query.until)) &&
+  (query.changes !== true || !isAllowedRead(entry));
+
 /** Where the page after `entries` starts, or `null` for an empty page. */
 export const auditCursorOf = (entries: readonly AuditEntry[]): AuditCursor | null => {
   const last = entries[entries.length - 1];
@@ -186,7 +244,8 @@ export function memoryAuditLog(opts: AuditLogOptions = {}): AuditLog {
       for (const sink of sinks) await sink.write(entry);
       return entry;
     },
-    async entries(query = {}): Promise<readonly AuditEntry[]> {
+    async entries(asked = {}): Promise<readonly AuditEntry[]> {
+      const query = auditWindow(SUBJECT, asked);
       const limit = auditLimit(SUBJECT, query);
       const before = query.before;
       // Insertion order reversed IS newest first, ties included: two entries of one millisecond
@@ -199,14 +258,7 @@ export function memoryAuditLog(opts: AuditLogOptions = {}): AuditLog {
             ? log.slice(0, at)
             : log.filter((entry) => newestFirst(before, entry) < 0);
       return older
-        .filter(
-          (entry) =>
-            (query.entity === undefined || entry.entity === query.entity) &&
-            (query.entityId === undefined || entry.entityId === query.entityId) &&
-            (query.actorId === undefined || entry.actor.id === query.actorId) &&
-            (query.orgId === undefined || entry.actor.orgId === query.orgId) &&
-            (query.changes !== true || !isAllowedRead(entry)),
-        )
+        .filter((entry) => auditEntryMatches(entry, query))
         .reverse()
         .slice(0, limit);
     },

package/src/crud-input.ts

@@ -66,22 +66,24 @@ export function withTenant(
 }
 
 /**
- * A field declared `on: 'create'` is set once and never patched; one declared `on: 'update'` has no
- * value until the row exists. The form does not draw either on the other side, and this is the
- * same rule for every caller that is not the form — an MCP call, a direct `adminUpdate`.
+ * Only what this resource lets a caller write, on this side. A `hidden` field is in no field
+ * list and a `readOnly` one (a generated column, the tenant, an override) is in the HTML form and
+ * the MCP schema for nobody, so a direct `adminCreate`/`adminUpdate` caller is cut the same way —
+ * skipping the form is not a way around it. A `sensitive` field stays writable: unreadable is not
+ * read-only. A field declared `on: 'create'` is set once and never patched; one declared
+ * `on: 'update'` has no value until the row exists.
  */
 export function onlyFor(
   resource: AdminResource,
   side: 'create' | 'update',
   input: Readonly<Record<string, unknown>>,
 ): Readonly<Record<string, unknown>> {
-  const other = new Set(
+  const offered = new Set(
     [...resource.fields, ...resource.secretFields]
-      .filter((field) => field.on !== undefined && field.on !== side)
+      .filter((field) => !field.readOnly && (field.on === undefined || field.on === side))
       .map((field) => field.name),
   );
-  if (other.size === 0) return input;
-  return Object.fromEntries(Object.entries(input).filter(([key]) => !other.has(key)));
+  return Object.fromEntries(Object.entries(input).filter(([key]) => offered.has(key)));
 }
 
 /**

package/src/detail.tsx

@@ -2,12 +2,13 @@
 // to this row, the row's history, and the actions this actor may run on it — each a link or a
 // native form, so the screen ships no script. A detail page with no row is a state, not a card.
 
+import { REDACTED } from '@ultimat3/core';
 import { t } from '@ultimat3/i18n';
 import { Button, Card, DataTable, ErrorState, Link } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import { AdminActions, ConfirmationField, DELETE_OPERATION, OPERATION_FIELD } from './actions';
 import styles from './admin.module.scss';
-import type { AuditCursor, AuditEntry } from './audit';
+import type { AuditEntry, AuditFieldDiff } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
 import { type AdminErrorParts, adminErrorFrom } from './errors';
 import { valueText } from './json-text';
@@ -55,6 +56,41 @@ export const operationLabel = (entry: AuditEntry): string =>
     ? t(`admin.action.${entry.operation}`)
     : t(`admin.operation.${entry.operation}`);
 
+/**
+ * The fields a diff never shows a value of: a `sensitive` field and a sealed column. The log is
+ * written redacted (`crud-input.ts`), and the view masks again, so an entry written by an app's own
+ * log, or before a field was marked, still draws no plaintext.
+ */
+export const maskedFieldsOf = (
+  resource: Pick<AdminResource, 'fields' | 'secretFields'>,
+): ReadonlySet<string> =>
+  new Set(
+    [...resource.fields, ...resource.secretFields]
+      .filter((field) => field.sensitive)
+      .map((field) => field.name),
+  );
+
+const shown = (masked: ReadonlySet<string>, field: string, value: unknown): string =>
+  value === undefined ? '' : masked.has(field) ? REDACTED : valueText(value);
+
+/** One entry's diff: field, before struck out, after inserted. Masked fields say only that. */
+export function AuditDiff(props: {
+  readonly diff: readonly AuditFieldDiff[];
+  readonly masked: ReadonlySet<string>;
+}): JSX.Element | null {
+  if (props.diff.length === 0) return null;
+  return (
+    <ul>
+      {props.diff.map((change) => (
+        <li>
+          <code>{change.field}</code>: <del>{shown(props.masked, change.field, change.before)}</del>{' '}
+          <ins>{shown(props.masked, change.field, change.after)}</ins>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
 export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>): JSX.Element {
   if (props.error !== null) {
     return <ErrorState error={adminErrorFrom(props.error)} />;
@@ -157,7 +193,7 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
 
       <Card header={<h2>{t('admin.audit.title')}</h2>}>
         {props.audit.length === 0 ? (
-          <p class="x-admin-empty">{t('admin.audit.empty')}</p>
+          <p class="x-admin-empty">{t('admin.audit.empty-row')}</p>
         ) : (
           <ol class="x-admin-audit">
             {props.audit.map((entry) => (
@@ -167,14 +203,7 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
                 <span data-outcome={entry.outcome}>
                   {t(`admin.audit.outcome.${entry.outcome}`)}
                 </span>
-                <ul>
-                  {entry.diff.map((change) => (
-                    <li>
-                      <code>{change.field}</code>: <del>{valueText(change.before)}</del>{' '}
-                      <ins>{valueText(change.after)}</ins>
-                    </li>
-                  ))}
-                </ul>
+                <AuditDiff diff={entry.diff} masked={maskedFieldsOf(props.resource)} />
               </li>
             ))}
           </ol>
@@ -186,23 +215,3 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
     </>
   );
 }
-
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/** The query parameter an older page of a row's history is asked for by: `?history=<at>~<id>`. */
-export const HISTORY_PARAM = 'history';
-
-/** The cursor as one parameter value — an ISO instant holds no `~`, a uuid neither. */
-export const historyCursorText = (cursor: AuditCursor): string => `${cursor.at}~${cursor.id}`;
-
-/** A posted-back cursor, or `undefined` for anything that is not one: page one, never an error. */
-export function historyCursorOf(raw: string | null): AuditCursor | undefined {
-  if (raw === null) return undefined;
-  const at = raw.indexOf('~');
-  if (at <= 0) return undefined;
-  const instant = raw.slice(0, at);
-  const id = raw.slice(at + 1);
-  // A uuid, because the durable log compares it as one: anything else would be a cast error from
-  // the database where a hand-edited URL deserves page one.
-  return Number.isNaN(Date.parse(instant)) || !UUID.test(id) ? undefined : { at: instant, id };
-}