@ultimat3/admin 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -9,69 +9,71 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **One authz.** `AdminAuthz` (`authz.ts`) is the only decision path. `action-gate.ts`, `crud.ts` and `page-guard.tsx` call `decideAll`; views render what the gate returned. Never add a second check in a view or an MCP handler.
 - **The subject carries the tenant and the loaded row.** `AdminActor.orgId` reaches `policyActor` and `AdminSubject.row` reaches `evaluate`; `adminDetail`/`adminUpdate`/`adminDestroy` load the row BEFORE the guard. `undefined` = not loaded (left off the subject), `null` = looked and found none (a row rule fails closed). Pinned in `policy-bridge.test.ts`, which asserts the SUBJECT a policy receives.
 - **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. A generated route's `component` was `null` and "the host binds an adapter" was a comment, so the deployed demo hand-wrote 1,781 lines of repo, screen glue and page files. `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`.
+- **`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.** Every 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 `''`.
-- **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>`, `?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.
+- **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.
 - **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` (`relationsFor`: 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. 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 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`.
+- **A page seeks on the PAIR `(sort, id)`** (`keyset-seek.ts`): the rest of the boundary's class by id, then past it, then the NULLs (last ascending, first descending), so any number of ties and a nullable sort column are positions; the cursor carries `null`, never `''`. An instant's class is its MILLISECOND — a row's `Date` drops Postgres' microseconds — read whole by id. `repo-entity-keyset(.contract).test.ts` walks to the end and back.
 - **A read by a mistyped id is a row that does not exist** — `repo-entity.ts`'s `find` answers `null` (the admin's 404); a write keeps the throw. An instant compared by the handle is a `Date`, never ISO text: the memory driver orders a string against a `Date` by its characters.
 - **Every admin document is `noindex, nofollow`**, a refusal and a 404 included (`route-config.ts`).
-- **A sealed column is written, never read.** `adminColumnsOf` skips `$meta.sealed`, so no field any screen reads by name exists for it; `resource.secretFields` is a list of its own that only the form (a password input, never a `value`) and `crud.ts` (`splitSecrets`: around `$schema`, empty = unchanged) touch. The audit diff is derived from that list, not from what a row enumerates. Pinned in `sealed-egress.test.ts`.
-- **The mount registry is on the global symbol registry** (`mounts.ts`, `Symbol.for('ultimate.admin.mounts')`), so the CLI can ask "did this app declare an admin?" without importing this package — importing it loads every screen and registers its stylesheets for an app that has none.
+- **A sealed column is written, never read.** `adminColumnsOf` skips `$meta.sealed`, so no field any screen reads by name exists for it; `resource.secretFields` is touched only by the form (a password input, never a `value`) and `crud.ts` (`splitSecrets`: empty = unchanged). The audit diff is derived from that list, not from what a row enumerates. Pinned in `sealed-egress.test.ts`.
+- **The mount registry is on the global symbol registry** (`mounts.ts`, `Symbol.for('ultimate.admin.mounts')`), so the CLI can ask "did this app declare an admin?" without importing this package.
 - **One `AdminAction.name`, one handler** — the MCP tool name, the default label key and `callAdminTool`'s lookup. A duplicate is `X_ADMIN_ACTION_DUPLICATE` at `defineAdmin`; identity, not name, is what "already seen" means.
 - **A `/_x` source reads a registry through its DESCRIPTOR TYPE, never as an untyped bag** — `import type { RouteDescriptor }` beside the dynamic `import()`; `dev/published-keys.test.ts` walks what the registries EMIT. A route fact carries `mount` (`{ by, permissions }` or `null`).
-- **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `hasMeta` was dropped because `defineRoute()` refuses a route with no `meta`, so `missingMeta` was a defect list with no member it could hold; `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key — a guarantee shown where the question is asked. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
-- **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describeRoutes()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
-- **The admin's stylesheets are claimed for `app/`** (`stylesheet-scope.ts`, `claimStylesheets`): a package sheet nobody claims rides both surface bundles, and a static `site/` document carried the dashboard's CSS. `stylesheet-scope.test.ts`.
-- **One bridge per foreign package.** `policy-bridge.ts` is the only file calling `evaluate`/`definePermissions`; `route-config.ts` the only one calling `defineRoute`/`registerMountedRoutes`; `mcp.ts` the only one calling `defineAppMcp`; `dev/data.ts` the only one importing introspection (dynamically — `/_x` must stay out of the production graph). Source only: a **test** declares the permissions its own `can()` fixtures use, because `definePermissions` writes a process-global registry and `bun test` seats several files in one process — `dev/data.test.ts` relied on the empty-registry-means-permissive fallback and went red the first time it shared a process with anything that imports this package.
+- **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
+- **The routes are in the framework's ONE route list, as mounted routes** — `route-config.ts` calls `registerMountedRoutes` at `defineAdmin`, so `describePages()` (`x routes`, `/_x`, `sw.js`, the manifest) lists each with `mount: { by: 'defineAdmin', permissions }` and `routeEntries()` holds none. `AdminApp.describe()` (`describe.ts`) is what the manifest's `admin` section records: filters, sorts, scopes, `rowScoped`, routes.
+- **The admin's stylesheets are claimed for `app/`** (`stylesheet-scope.ts`, `claimStylesheets`). `stylesheet-scope.test.ts`.
+- **Importing this package declares NO permission.** `defineAdmin()` calls `declareAdminPermissions`, which registers `ADMIN_PERMISSIONS` plus what the mount derives (`policy-bridge.test.ts`).
+- **One bridge per foreign package.** `policy-bridge.ts` → `evaluate`/`definePermissions`; `route-config.ts` → `defineRoute`/`registerMountedRoutes`; `mcp.ts` → `defineAppMcp`; `dev/data.ts` → introspection, dynamically. A test declares its own fixtures' permissions and calls `defineAdmin()` in `beforeAll`, never at module scope.
 - **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
 - **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
-- **A deliberate query loop declares itself.** `search.ts` runs one indexed lookup per text field on purpose — the query IR is a conjunction, so three small indexed reads beat one unindexed `OR` — and says so through `expectedQueryLoop()` from `@ultimat3/db` (tier 1, downward, and the only thing this package imports from it). That is the one suppression mechanism: never a comment pragma and never a list of exempt call sites. A new loop here either argues for itself in a `reason` or it is an N+1.
+- **A deliberate query loop declares itself** — `expectedQueryLoop()` from `@ultimat3/db`, with a `reason` (`search.ts`, `batch.ts`, `relations.ts`). Never a comment pragma, never an exempt list; an undeclared loop is an N+1.
 - **The timeline panel renders the detector's verdicts** (`DevSources.statementLoops()`), never a second count; none wired is `null`, never `[]`.
-- **This catalog is the framework's one opt-OUT MCP surface, and that is deliberate.**
-  `mcp-tools.ts` is the only file that does not call `isMcpExposed` from `@ultimat3/core`: every
-  tool here is already gated on an admin permission, and the CRUD tools carry no `mcp` block at
-  all, so opting in would list `admin.posts.delete` while hiding the action button beside it.
-  `mcp: { expose: false }` withdraws one. Stated there, in core's `mcp-exposure.ts`, and in
-  `wiki/Admin-Dashboard.md` — a *second* exception anywhere is the bug.
+- **This catalog is the framework's one opt-OUT MCP surface, deliberately**: `mcp-tools.ts` does not call `isMcpExposed` — every tool is already gated on an admin permission. `mcp: { expose: false }` withdraws one. A *second* exception anywhere is the bug.
 - **`dev/panel-db.ts`'s `sanitize` decides "did they type a statement", not "is it safe"** — never cite it as a security property.
-- **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider: a bare `catch` in `dev/panel-live.ts` reported an authz refusal and a dropped NATS connection from a *running* sync node as `dev.live.no-sync-node`, telling the reader to install a tier they already had. Everything else reaches `panelPayload`, which renders its code and its fix.
-- **What an entity does not declare, the admin does not invent.** `sensitive`, a fixed `currency` and `labelField` come from `AdminResourceOptions` or they are absent. Same rule for a URL: the reference widget links through `WidgetContext.hrefFor` or renders plain text — it used to build `/${entity}s/${id}`, which is English pluralisation by concatenation and drops `basePath`. The route table is `AdminApp`'s; a widget three layers down does not get to guess it.
+- **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider — in `panel-live`, `panel-db`, `panel-timeline` and `panel-cache` alike (`dev/panel-degrade.test.ts`). Everything else reaches `panelPayload`, which renders its code and its fix.
+- **What an entity does not declare, the admin does not invent.** `sensitive`, a fixed `currency` and `labelField` come from `AdminResourceOptions` or they are absent. Same rule for a URL: the reference widget links through `WidgetContext.hrefFor` or renders plain text — the route table is `AdminApp`'s.
 - **`panel-db.ts` executes the string `assertReadOnlyQuery` RETURNS**, never the textarea's bytes (`ReadOnlyVerdict`).
 - **`decideAll([])` DENIES** (`admin.policy.none-declared`): an empty gate is a refusal for everyone, never a grant.
 - **Two resources may not claim one `path:`** — `X_ADMIN_PAGE_PATH_INVALID` (`subject: 'resource'`) at `defineAdmin`, every generated path included.
 - **The audit diff is TOTAL over every value a row holds** — compared with core's `canonicalJson`, never `JSON.stringify` (a `money()` bigint throws there, after the write committed).
-- **A write that does not happen leaves a `failed` entry** (`crud-outcome.ts`): a repo that throws (`auditedWrite` — try, record, re-throw UNCHANGED), an input the schema refused, a row that was not there. The reason is a key, never anything read off a thrown value.
-- **Nothing is read off a caught value in `action-gate.ts`, and the append runs first.**
+- **A write and its entry commit together** (`atomicallyAudited`, `crud-outcome.ts`): a CRUD write, an action's handler, `matching` and a queued batch's enqueues each run inside `audit.atomic` with their `allowed` entry, so an entry that cannot be written rolls the work back; ONE `failed` entry is appended after, outside, and the thrown value is re-thrown UNCHANGED with nothing read off it. A schema refusal and a missing row are `failed` too. `audit-atomic(.contract).test.ts`.
+- **An edit is optimistic** (`row-version.ts`): the form posts `_version` = `rowVersion(row)` (keyed), `adminUpdate(…, { version })` answers `stale` — 409, `admin.error.row-changed`, the form re-drawn over the row as it is now — when the row moved on; a post with no version is stale. An instant posted back as it was drawn (`datetimeInputValue`) is LEFT OUT of the patch (`decodeForm(…, before)`): `datetime-local` holds minutes. A create or update is decided again on the validated values as `subject.input` (update: beside `row`).
+- **The audit trail is the actor's tenant's**: `/admin/audit` and the history card pass `orgId` to `entries()` when the actor has one (`audit-tenancy.test.ts`).
 - **A table read by a runtime key is `Object.hasOwn` / a `Map`, never a bare index** — `impliedBy`, the `/_x` counters, `list-filters.ts`' operator table, `renderers.tsx` (`bun run proto-index`).
+- **The `/_x` SQL runs in `readOnlyQuery`** (`dev/sql-runner.ts`, `readOnlySql(client)` — what a host wires as `runSql`): read-only transaction, timeout, `DEV_SQL_MAX_ROWS`.
 - **One read-only SQL guard, and it is `@ultimat3/mcp`'s** — no local keyword scan; the panel keeps only the emptiness test and the way out (`psql "$DATABASE_URL"`, the developer's own client — `x db` has no `psql`).
-- **Every admin operation is audited, reads included.** `adminList` was the one call that logged nothing in either direction; `ListResult` now carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`), because the subject of a listing is not a row. `adminSearch` was the second, and it read rows out of EVERY readable entity: `AdminSearchResult.audit` now carries one entry per resource it decided about — `allowed` per searched resource, a `deniedDraft` per refused one. A resource skipped for having no text field or no repo is not an authz event and writes none.
+- **Every admin operation is audited, reads included**, not `/admin`'s counts (a count reads no row). `ListResult` carries its `AuditEntry` on both branches (`entityId: null`); `AdminSearchResult.audit` one entry per resource decided, and a skipped resource (no text field, no repo, a repo that threw) is in `skipped`, never a 500.
 - **A write's RESULT satisfies the actor's row scope** (`row-scope-write.ts`): a create, and an update over the fields it touches, outside `rows(actor)` is refused before the repo — `admin.error.row-out-of-scope`, audited as a denial. The one predicate evaluator in this package; an ordering over text is refused, never guessed. `row-scope-write.test.ts`.
 - **An action's `when(row)` is asked by the button AND by the call** (`actionApplies`, `action-gate.ts`): a row it excludes is `X_ADMIN_ACTION_NOT_APPLICABLE` (409 on a screen, the code over MCP), audited `admin.error.action-not-applicable`. The row it reads carries no sealed column. Every action on one row runs through `invokeRowAction` (`findRow` first).
 - **An action with an `input` schema is a form, never a bare post**: its button links to `<row>?action=<name>`, the form posts `input.<field>` (`action-input.ts`, through `tryIntrospect`), the gate validates against the schema and a refusal is a 422 with issues on their fields. No schema: a confirm only.
-- **A batch is the button's gate once per row** (`batch.ts`): policy, `when`, handler; counts `done`/`refused`/`failed`/`queued`/`remaining`; one audit entry per row. Selection is checked ids or "all matching" — the list URL's own `listWhere`, keyset by id, `MAX_BATCH_ROWS` inline / `MAX_BATCH_QUEUED_ROWS` queued per request. `batch: { threshold }` queues one `admin.batch` job per chunk (`batch-job.ts`), declared at `defineAdmin`; the worker runs it AS the operator. Zero JS: the bar is one form (`batch-bar.tsx`), row checkboxes join it by `form=`; a destructive or input-taking batch is a server round trip. ONE MCP tool per action — a batch action's tool takes `ids`.
+- **A batch is the button's gate once per row** (`batch.ts`): policy, `when`, handler, one audit entry each. Checked ids or "all matching" (`listWhere`, keyset by id, `MAX_BATCH_ROWS` / `MAX_BATCH_QUEUED_ROWS`). `batch: { threshold }` queues `admin.batch` jobs under a derived `batchIdOf`, run AS the operator. Zero JS (`batch-bar.tsx`). ONE MCP tool per action — a batch action's tool takes `ids`.
 - **Sections and form groups never hide a field** (`resource-layout.ts`): undeclared fields fall into a default group drawn last; a name that is not a drawn field, or claimed twice, is refused at `defineAdmin`. `on: 'create' | 'update'` is enforced on the write too (`onlyFor`, `crud-input.ts`).
 - **A related list IS the related resource's list** (`related.ts`): a `hasMany` of the entity, read through `adminList` (its gate, its `rows`), filtered to this row; a resource the actor may not list is left out. One label read per target for the whole detail page.
 - **The audit log is the store, a sink is a copy.** `AuditLog.entries()` is async, keyset (`before`), `changes: true` drops allowed reads; `atomic(run)` puts a write and its entry in one transaction (`auditedWrite`). `postgresAuditLog()` writes `x_admin_audit` (`audit-pg.ts`), skips allowed reads unless `reads: true`. `audit-pg.contract.test.ts` boots PGlite.
-- **The jobs dashboard is every admin's, built from these pieces only** (`jobs/`): four resources — `x_jobs`, `x_job_queues`, `x_job_tasks`, `x_job_workers` — each with a `repo:` over `JobIntrospection` (`job-repo.ts`, `fleet-repo.ts`), scopes, a row scope and `job-actions.ts`'s `AdminAction`s, plus ONE screen (`overview.tsx`, the view `jobs`). `job:read` lists them (the resources' `permission` noun is `job`), `job:manage` runs every action. An actor with an `orgId` sees that org's job rows and none of the fleet. `jobs/boundary.test.ts` refuses a `fetch(`, a socket, an event stream or a hand-written table there; `/_x/jobs` draws `JobsOverview` over the dev queue (`dev/panel-jobs.ts` → `jobs/overview-tab.tsx`, dynamically).
+- **The jobs dashboard is every admin's, built from these pieces only** (`jobs/`): resources `x_jobs`, `x_job_queues`, `x_job_tasks`, `x_job_workers` with `repo:`s over `JobIntrospection`, scopes, a row scope and `job-actions.ts`, plus ONE screen (`overview.tsx`). `job:read` lists, `job:manage` acts; an `orgId` actor sees its org's jobs and none of the fleet. `jobs/boundary.test.ts`.
 - **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`.
+- **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). Without this, an action declaring no `when` ran its handler on an id outside the actor's `rows`.
+- **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.
-- Money through `assertMoney`, timestamps through `assertZone`, pagination through `pagination.ts`. No `offset`, ever.
+- 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.
 - **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`, no local state, no event handler.
-- **No test reaches a `.tsx` statically.** `routes.ts` reaches the screens, so a test does `await import('@ultimat3/render/server')` and then `await import('./routes')`: a static import compiles JSX before the loader exists and every later render dies with `React is not defined`.
+- 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')`.
 
 ## Layout
 
@@ -84,15 +86,15 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 | `list-request.ts` / `list-filters.ts` / `list-scope.ts` | URL ⇄ list request / operators per shape + the validator / row scope → scope → filters, `findRow`, `scopeCounts` |
 | `list.tsx` / `list-filter-bar.tsx` / `list-scope-tabs.tsx` / `renderers.tsx` | the list view / one GET form / tabs as links / computed cells |
 | `resource-list.ts` / `relations.ts` / `describe.ts` | `scopes`·`rows`·`columns` normalised / labels + lookup, one read per target / the admin as manifest data |
-| `repo-entity.ts` / `form-decode.ts` | typed handle → `AdminRepo` / posted form → typed input |
+| `repo-entity.ts` / `keyset-seek.ts` / `form-decode.ts` / `row-version.ts` | typed handle → `AdminRepo` / the `(sort, id)` seek / posted form → typed input / an edit's version |
 | `registry.ts` / `entity-columns.ts` | the entity surface the admin reads / one entity → column facts |
 | `resource.ts` / `fields.ts` / `widget-value.ts` | derivation, widget table, value guards |
 | `crud.ts` / `crud-input.ts` / `crud-outcome.ts` / `action-gate.ts` / `row-scope-write.ts` | policy → confirmation → validation → repo → audit / secrets, tenant, sides, diff / the entry of a write that did not happen / a write's result vs `rows` |
 | `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-bar.tsx` / `batch-job.ts` | a batch through the gate / the bar and row checkboxes / the `admin.batch` job |
+| `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 |
-| `mcp-tools.ts` / `mcp.ts` | tool derivation (pure) / transport wiring |
+| `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 |
 | `batch-matching.ts` / `audit-schema.ts` | a set-based "all matching" / the audit table's DDL, a leaf |

package/README.md

@@ -8,7 +8,7 @@
 | Audience | you, debugging the framework | your operators, and their agents |
 | Environment | development **only** — mounting it with `env=production` or `role=production` throws `X_DEV_DASHBOARD_IN_PROD` | production |
 | Authz | none: it is your own machine | the app's policies, one decision per surface |
-| Data | introspection calls (`describeRoutes`, `inspect`, `dependentsOf`, …) | the entity registry + repos |
+| Data | introspection calls (`describePages`, `inspect`, `dependentsOf`, …) | the entity registry + repos |
 | Shipped in the app image | never mounted | mounted at `/admin` |
 
 ## `/_x` panels
@@ -18,10 +18,10 @@ One panel per file. Each kills one question, and each is available as `--json`
 | Panel | Kills |
 |---|---|
 | `routes` | which handler serves this? — render mode, offline strategy, revalidate tags, budget |
-| `timeline` | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count |
+| `timeline` | where did the time go? — a server-rendered waterfall of SQL, cache, action, policy spans (one row per span, bar placed by the payload's own `offset`/`width`), time per kind, and the N+1 detector's verdicts with their fix lines; the payload folded under it |
 | `live` | what does each subscriber receive, and **why** — the matcher's decision trace |
-| `jobs` | 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; `assertReadOnly` refuses DML), schema + drift (`null` unless a host wires the check) |
+| `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 |
 | `cache` | the tag graph — what invalidated what, and which tags are orphans |
 | `policy` | the permission matrix per actor, every cell carrying its trace |
@@ -36,6 +36,8 @@ const authz = staticAuthz(['admin:read']);
 const actors = [{ id: 'dev-admin', roles: ['admin'] }];
 
 const dev = devDashboard({ sources: defaultDevSources({ authz, actors }) }); // throws in prod
+// A drawn tab renders ui's components; their rules are in the app surface's stylesheet, so a host
+// names its URL: devDashboard({ …, stylesheetHref: () => styleBundle().hrefFor('app') })
 const response = await dev.handle(request); // null when the path is not /_x
 await dev.json('jobs'); // the same payload /_x/jobs renders from
 ```
@@ -62,12 +64,22 @@ export const admin = defineAdmin({ entities: [posts, users], db });
 `/admin/posts/<id>`, `/admin/posts/<id>/edit`, plus `/admin/search`, `/admin/audit` and the jobs
 dashboard (`/admin/jobs`, below).
 
+`/admin` itself opens on a KPI row — one `StatTile` per resource the actor may list AND that
+declared `resources.<entity>.count: true`, its figure that resource's `AdminRepo.count()` over its
+`rows` scope, each tile a link to the list — and a `DonutChart` of the same counts, then the
+permission matrix per resource. Opt-in, as a scope tab's `count` is: a tile is one full `count()`
+per visit, so an operator reloading the front page over a big table is a load generator. A resource
+the actor may not list has no tile, no segment and no matrix; one that did not opt in, a repo with no
+`count()`, or one whose count the store refuses (`X_TENANCY_UNSCOPED` for an actor with no org), has
+no tile and never fails the page. A count reads no row, so it is not audited. Each matrix is a
+closed `<details>` whose summary reads "N of M allowed".
+
 | Input | What it is | Omitted |
 |---|---|---|
 | `entities` | the objects `entity()` returned — `adminEntitiesOf(db)` is every entity the handle serves | required |
 | `db` | the app's `database()` handle. Each resource reads through its own table: tenancy, soft delete, sealing and invariants are the handle's, and the admin adds no predicate | `resources.<entity>.repo` per resource, or `X_ADMIN_REPO_UNBOUND` at declaration |
-| `resources` | per-entity overrides — `listFields`, `labelField`, `columns`, `scopes`, `rows`, `sections`, `formGroups`, `related`, `fields.<name>.{sensitive,hintKey,on}`, `operations`, `repo`, `permission` (the noun its operations are named after; default the entity's name) | derived |
-| `actions` | `AdminAction[]` — a `permission` (never optional) plus a handler; optional `input` schema, `when(row)`, `batch` | none |
+| `resources` | per-entity overrides — `listFields`, `labelField`, `columns`, `scopes`, `count` (a tile on `/admin`), `rows`, `sections`, `formGroups`, `related`, `fields.<name>.{sensitive,hintKey,on}`, `operations`, `repo`, `permission` (the noun its operations are named after; default the entity's name) | derived |
+| `actions` | `AdminAction[]` — a `permission` (never optional) plus a handler; optional `input` schema, `when(row)`, `batch`, `readonly`, `destructive` | none |
 | `pages` | custom screens, see below | none |
 | `auth.actor` | who is acting | the actor the HTTP pipeline resolved for the request |
 | `auth.authz` | the one decision path | `roleAuthz()` — the role map decides each permission by name |
@@ -91,11 +103,11 @@ The list's whole state is its URL — one parser and one builder (`pageRequestOf
 
 | Parameter | Means | Refused when |
 |---|---|---|
-| `?cursor=<signed>` | keyset position | never — an unreadable cursor is page one |
+| `?cursor=<signed>` | keyset position on `(sort, id)` — any number of tied values, and NULLs (last ascending, first descending), are reached | never — an unreadable cursor is page one |
 | `?sort=<field>:<asc\|desc>` | order; a bare field is `desc` | the field is not sortable, or the direction is neither |
-| `?scope=<name>` | a declared scope; absent is the default one | no scope has that name |
+| `?scope=<name>` | a declared scope; absent is the default one; `*` is NO scope, not even the default (a related card's "all" link) | no scope has that name; `*` cannot be declared |
 | `?f.<field>=<value>` | a filter, by the field's default operator | the field is not a filter of the resource |
-| `?f.<field>.<op>=<value>` | a named operator; repeat the parameter for `in` | the field's shape does not answer `<op>`, or the value is not the column's type |
+| `?f.<field>.<op>=<value>` | a named operator; repeat the parameter for `in` | the field's shape does not answer `<op>`, or the value is not the column's type — a number is decimal digits (no blank, hex or exponent), a date is one the calendar has |
 | anything else | — | always |
 
 A refusal is `X_ADMIN_FILTER_INVALID`, a 400 naming what the list does answer — never the
@@ -179,8 +191,9 @@ export const resources: Readonly<Record<string, AdminResourceOptions>> = {
 | `on` | the field is an input on one side only, and a write from the other side drops it |
 | `hintKey` | the line under the control, through `t()` |
 
-The detail page's history card is `audit.entries({ entity, entityId, changes: true })`, newest
-first, 20 per page, older pages by keyset (`?history=`). Statements a detail page issues: 1 for
+The detail page's history card is `audit.entries({ entity, entityId, changes: true })` — and
+`orgId` when the actor has one, as on `/admin/audit` — newest first, 20 per page, older pages by
+keyset (`?history=`). Statements a detail page issues: 1 for
 the row (2 with `rows`), 1 per related list, 1 per referenced target for the whole page, 1 for
 the history with `postgresAuditLog`.
 
@@ -210,7 +223,8 @@ export const suspendUser: AdminAction = {
 | `batch` | the list's batch bar — checked rows, or every row the list's URL matches — each row through the button's gate and on the audit log, answered with `done` / `refused` / `failed` / `queued` / `remaining`. 200 rows inline per request (`MAX_BATCH_ROWS`), 1,000 queued (`MAX_BATCH_QUEUED_ROWS`); "all matching" continues from where it stopped |
 | `matching` | "all matching" as ONE set-based call: handed the list's `where` (row scope, scope, filters), it answers `{ affected, remaining }` — a store's bounded bulk verb. Decided and audited once (`admin.batch.matching`); a destructive one types `<entity>:all matching`. Checked rows still run row by row. Requires `batch` |
 | `batch.threshold` | past it, one `admin.batch` job per `chunk` (default: the threshold), run by a worker as the operator who queued it. The worker must load the module calling `defineAdmin` (`X_ADMIN_MOUNT_MISSING`) |
-| destructive | one row: type `<entity>:<id>`; a batch: type `<entity>:<n> rows` |
+| `readonly` | the action changes nothing (an export, a verification): its admin-level gate is `admin:read`, not `admin:write`, so a read-only staff role and an `admin:read` MCP token may run it. `destructive` (`admin:destroy`) and `matching` (`admin:write`) win over it |
+| destructive | gated on `admin:destroy`; one row: type `<entity>:<id>`; a batch: type `<entity>:<n> rows` |
 | MCP | still ONE tool, `admin.action.<name>`; a batch action's takes `ids: [...]` |
 | `labelKey` | the button's, the form's and the batch bar's label; absent: `admin.action.<name>` |
 
@@ -249,12 +263,15 @@ admin's own projection. `/_x/jobs` draws the same overview component over the de
 ### The audit log
 
 `postgresAuditLog()` writes one row per audited write to `x_admin_audit`, in the same
-transaction as the write (`AuditLog.atomic`), and reads it back by keyset. An allowed READ is not
+transaction as the write (`AuditLog.atomic`) — a CRUD write, an action's handler, a `matching`
+set and a queued batch's enqueues alike, so an entry that cannot be written rolls the work back
+and the log holds one `failed` entry — and reads it back by keyset. An allowed READ is not
 written unless `reads: true` — a refused one always is. Sealed and `sensitive` values reach the
-table only as `[redacted]`. `memoryAuditLog()` is a ring that forgets at every restart. The
+table only as `[redacted]` — `@ultimat3/core`'s `REDACTED`, the logger's marker too. `memoryAuditLog()` is a ring that forgets at every restart. The
 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.
+no migration, no screen loaded to install it. That subpath is their one import path: 25.0.0 took
+them off the barrel.
 
 ### A sealed column
 
@@ -406,6 +423,7 @@ shape already is, written down once so two apps do not invent two layouts. `x g
 | A button an actor cannot press is never rendered, and the call is refused by the same decision | `action-gate.ts` |
 | Destructive operations re-confirm (`<entity>:<id>`) and are always audited | `permissions.ts`, `crud.ts` |
 | Every mutation and every denial is on the audit log, with a before/after diff | `audit.ts` |
+| An edit carries the row's version (`_version`); a row changed since the form was drawn is a 409, never overwritten. An instant posted back as drawn is left out of the patch | `row-version.ts`, `form-decode.ts` |
 | Branding aliases tokens only — `accent: '#7c3aed'` is a compile error | `theme.ts` |
 
 Reads are audited too, and on both branches: `adminDetail` keys its entry on the row,
@@ -424,6 +442,23 @@ export const mcp = adminMcp({ app: admin, actor: (session) => actorFor(session.t
 adminMcpTools(admin, ctx); // admin.post.list · admin.post.read · admin.search · admin.action.post.publish
 ```
 
+Every tool carries a **scope**, the admin-level permission it needs. The MCP registry asks, in
+order: visibility — the actor's own admin authz (`adminMcpTools`); a tool it denies is ABSENT and
+answers tool-not-found, whatever the token holds — then the token's scope (`X_MCP_SCOPE_DENIED`
+naming it, before any argument is validated or a handler runs), then the call's own row-level
+decision inside the tool:
+
+| Scope | Tools |
+|---|---|
+| `admin:read` | `admin.<entity>.list`, `admin.<entity>.read`, `admin.search`, a `readonly` action |
+| `admin:write` | `admin.<entity>.create`, `admin.<entity>.update`, any other action |
+| `admin:destroy` | `admin.<entity>.delete`, a `destructive` action |
+
+The token's scopes are what `actor(session)` returns as `tokenScopes` (`AdminMcpActor`), expanded by
+`adminTokenScopes` (`admin:destroy` ⇒ `admin:write` ⇒ `admin:read`): `tokenScopes: ['admin:read']`
+is a read-only agent token. Absent, the token is as strong as its actor. A stdio host builds its
+caller's `scopes` with `adminTokenScopes(granted)` too — an empty set is refused every tool.
+
 The list tool takes the list screen's own grammar: `scope` by name and `where` as
 `[{ field, op?, value }]`, through the same validator a URL passes — and the resource's `rows`
 narrows what an agent reads whatever it sends.
@@ -460,4 +495,4 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `AdminPolicyMissingError` | `X_ADMIN_POLICY_MISSING` | `src/errors.ts` |
 | `AdminRepoUnboundError` | `X_ADMIN_REPO_UNBOUND` | `src/errors.ts` |
 | `DevDashboardInProdError` | `X_DEV_DASHBOARD_IN_PROD` | `src/errors.ts` |
-| `DevSourceUnavailableError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `DevSourceUnavailableError` (extends core's `NotImplementedError`) | `X_NOT_IMPLEMENTED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -27,27 +27,27 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "23.0.0",
-    "@ultimat3/ai": "23.0.0",
-    "@ultimat3/cache": "23.0.0",
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/db": "23.0.0",
-    "@ultimat3/entity": "23.0.0",
-    "@ultimat3/i18n": "23.0.0",
-    "@ultimat3/jobs": "23.0.0",
-    "@ultimat3/mcp": "23.0.0",
-    "@ultimat3/money": "23.0.0",
-    "@ultimat3/policy": "23.0.0",
-    "@ultimat3/query": "23.0.0",
-    "@ultimat3/render": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/ui": "23.0.0"
+    "@ultimat3/action": "25.0.0",
+    "@ultimat3/ai": "25.0.0",
+    "@ultimat3/cache": "25.0.0",
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/db": "25.0.0",
+    "@ultimat3/entity": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/jobs": "25.0.0",
+    "@ultimat3/mcp": "25.0.0",
+    "@ultimat3/money": "25.0.0",
+    "@ultimat3/policy": "25.0.0",
+    "@ultimat3/query": "25.0.0",
+    "@ultimat3/render": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/ui": "25.0.0"
   }
 }

package/src/action-gate.ts

@@ -12,10 +12,13 @@ import {
   type AdminSubject,
   decideAll,
 } from './authz';
+import { atomicallyAudited } from './crud-outcome';
 import { AdminActionNotApplicableError } from './errors';
 import {
   ADMIN_DESTROY,
+  ADMIN_READ,
   ADMIN_WRITE,
+  type AdminPermission,
   CONFIRMATION_REQUIRED_REASON,
   confirmationToken,
 } from './permissions';
@@ -46,11 +49,26 @@ export const ACTION_NOT_APPLICABLE_REASON = 'admin.error.action-not-applicable';
 /** The reason an action whose input its own schema refused is audited with. */
 const ACTION_INVALID_REASON = 'admin.error.invalid-input';
 
+/**
+ * The admin-level gate an action needs, and the MCP scope its tool carries. `destructive` is
+ * checked first so a declaration marked both `readonly` and `destructive` gets the stricter gate —
+ * a contradiction that fails closed rather than open.
+ */
+export function adminPermissionForAction<Input, Output>(
+  action: AdminAction<Input, Output>,
+): AdminPermission {
+  if (action.destructive === true) return ADMIN_DESTROY;
+  // `matching` CHANGES every row the list matches (its contract answers how many it changed), so a
+  // `readonly` beside it is the same contradiction as beside `destructive`: the write gate holds.
+  if (action.matching !== undefined) return ADMIN_WRITE;
+  return action.readonly === true ? ADMIN_READ : ADMIN_WRITE;
+}
+
 /** The permissions an action needs: the admin-level gate, then the action's own policy. */
 export function permissionsForAction<Input, Output>(
   action: AdminAction<Input, Output>,
 ): readonly string[] {
-  return [action.destructive === true ? ADMIN_DESTROY : ADMIN_WRITE, action.permission];
+  return [adminPermissionForAction(action), action.permission];
 }
 
 export function decideAction<Input, Output>(
@@ -278,51 +296,24 @@ export async function invokeAdminAction<Input, Output>(
     timeZone: args.timeZone ?? actor.timeZone ?? 'UTC',
   };
 
-  try {
-    const value = await action.handle({ input, ctx });
-    return {
-      ok: true,
-      value,
-      audit: await audit.append({
-        requestId,
-        actor,
-        operation: action.name,
-        kind: 'action',
-        entity,
-        entityId,
-        permission: action.permission,
-        outcome: 'allowed',
-        reason: decision.reason,
-        diff: args.diff ?? [],
-      }),
-    };
-  } catch (error) {
-    // NOTHING is read off `error` before the append, and nothing is read off it at all.
-    //
-    // This built an `AdminDecision` first, whose `trace` rendered the caught value with
-    // `String(error)` — and a `catch` binding is annotated by nobody, so it holds whatever an
-    // app's handler threw. `Object.create(null)` has no `toString`, no `valueOf` and no
-    // `Symbol.toPrimitive`, so `String(it)` raises `TypeError: No default value` from inside the
-    // block that owes the auditor an entry: measured, ZERO entries, and the caller received the
-    // TypeError instead of what was thrown. Ordering was the second half — the render ran BEFORE
-    // `append`, so its throw skipped the append rather than merely spoiling one field.
-    //
-    // The decision object was also DEAD: only its `reason` was ever read, and `append` takes no
-    // trace. So there is no destination for a rendered value here and `renderThrowable` is not
-    // needed either — an audit reason is a key the view renders, never a sentence from a
-    // database, an upstream or an attacker.
-    await audit.append({
+  // The handler and its entry are ONE unit (`atomicallyAudited`): a handler whose writes ride the
+  // ambient transaction commits with its `allowed` entry or not at all, and a throw from either
+  // leaves exactly one `failed` entry, appended after the rollback, with nothing read off the
+  // thrown value — which reaches the caller unchanged.
+  const { value, audit: appended } = await atomicallyAudited(
+    audit,
+    {
       requestId,
       actor,
       operation: action.name,
       kind: 'action',
       entity,
-      entityId,
       permission: action.permission,
-      outcome: 'failed',
-      reason: ACTION_FAILED_REASON,
-      diff: [],
-    });
-    throw error;
-  }
+    },
+    { allowed: decision.reason, failed: ACTION_FAILED_REASON },
+    entityId,
+    () => action.handle({ input, ctx }),
+    () => ({ entityId, diff: args.diff ?? [] }),
+  );
+  return { ok: true, value, audit: appended };
 }