@ultimat3/admin 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -9,51 +9,50 @@ 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 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.
+- **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 `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.
+- **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` 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, and calls `defineAdmin()` in `beforeAll`, NEVER at module scope — the leak guard keeps what a file's module scope registered for every later file, so one module-scope admin closed the permission set for `bun test packages/admin packages/query`.
 - **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.** `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` — as do `batch.ts` (one row at a time) and `relations.ts` (label reads chunked at 200 ids, never cut). 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.
 - **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.** `ListResult` carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`). `AdminSearchResult.audit` carries one entry per resource it decided about — `allowed` per searched resource, a `deniedDraft` per refused one; a resource skipped for no text field, no repo or a repo that THREW (`admin.search.skipped.failed`) is listed in `skipped`, never a 500 for the rest.
 - **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; 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-queue.ts`, `batch-job.ts`) under a DERIVED `batchIdOf` (actor, action, rows, input — not the request id), so a retry dedupes; 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`.
 - **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.
@@ -61,7 +60,7 @@ 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`.
 - **`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.
@@ -84,12 +83,12 @@ 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 |

package/README.md

@@ -21,7 +21,7 @@ One panel per file. Each kills one question, and each is available as `--json`
 | `timeline` | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count |
 | `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) |
+| `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 |
@@ -91,11 +91,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 +179,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`.
 
@@ -249,7 +250,9 @@ 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 is applied at boot with every other framework table (`@ultimat3/cli`'s `FRAMEWORK_SCHEMA`),
@@ -406,6 +409,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,
@@ -460,4 +464,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": "24.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -34,20 +34,20 @@
     "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": "24.0.0",
+    "@ultimat3/ai": "24.0.0",
+    "@ultimat3/cache": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/i18n": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/mcp": "24.0.0",
+    "@ultimat3/money": "24.0.0",
+    "@ultimat3/policy": "24.0.0",
+    "@ultimat3/query": "24.0.0",
+    "@ultimat3/render": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/ui": "24.0.0"
   }
 }

package/src/action-gate.ts

@@ -12,6 +12,7 @@ import {
   type AdminSubject,
   decideAll,
 } from './authz';
+import { atomicallyAudited } from './crud-outcome';
 import { AdminActionNotApplicableError } from './errors';
 import {
   ADMIN_DESTROY,
@@ -278,51 +279,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 };
 }

package/src/batch-matching.ts

@@ -4,6 +4,7 @@
 
 import type { AdminDecision } from './authz';
 import type { CrudCtx } from './crud';
+import { atomicallyAudited } from './crud-outcome';
 import { type AdminListRequest, listWhere } from './list-scope';
 import { ADMIN_DESTROY, CONFIRMATION_REQUIRED_REASON, confirmationToken } from './permissions';
 import type { AdminAction, AdminActionCtx, AdminMatchingResult } from './registry';
@@ -57,36 +58,30 @@ export async function runMatching(args: MatchingInput): Promise<MatchingAnswer>
     locale: ctx.actor.locale ?? 'en',
     timeZone: ctx.actor.timeZone ?? 'UTC',
   };
-  const entry = {
-    requestId: ctx.requestId,
-    actor: ctx.actor,
-    operation: action.name,
-    kind: 'action',
-    entity: resource.name,
-    entityId: null,
-    permission: args.decision.permission,
-  } as const;
-  let result: AdminMatchingResult;
-  try {
-    result = await action.matching({ where, input: args.input, ctx: actionCtx });
-  } catch (error) {
-    // The gate's rule: the failure is recorded before it travels, and nothing is read off it.
-    await ctx.audit.append({
-      ...entry,
-      outcome: 'failed',
-      reason: MATCHING_FAILED_REASON,
-      diff: [],
-    });
-    throw error;
-  }
-  await ctx.audit.append({
-    ...entry,
-    outcome: 'allowed',
-    reason: BATCH_MATCHING_REASON,
-    diff: [
-      { field: 'affected', before: null, after: result.affected },
-      { field: 'remaining', before: null, after: result.remaining },
-    ],
-  });
+  // The set-based write and its one entry commit together or not at all — a `matching` verb that
+  // rides the ambient transaction is rolled back with an entry that could not be written, and the
+  // log says `failed` (`atomicallyAudited`). It used to append AFTER the call, outside any `try`:
+  // a sink that threw left a committed write with no entry at all.
+  const { value: result } = await atomicallyAudited(
+    ctx.audit,
+    {
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: action.name,
+      kind: 'action',
+      entity: resource.name,
+      permission: args.decision.permission,
+    },
+    { allowed: BATCH_MATCHING_REASON, failed: MATCHING_FAILED_REASON },
+    null,
+    () => action.matching({ where, input: args.input, ctx: actionCtx }),
+    (answered) => ({
+      entityId: null,
+      diff: [
+        { field: 'affected', before: null, after: answered.affected },
+        { field: 'remaining', before: null, after: answered.remaining },
+      ],
+    }),
+  );
   return { ok: true, result };
 }

package/src/batch-queue.ts

@@ -0,0 +1,90 @@
+// The queued half of a batch past its declared threshold: every chunk enqueued and the one entry
+// naming them, as ONE audited unit, under a batch id DERIVED from the request's content — so a
+// retry after a failed enqueue asks the queue for the chunks it already holds.
+
+import { keyedFingerprint } from '@ultimat3/core';
+import type { AdminDecision } from './authz';
+import type { AdminBatchInput, BatchEnqueue } from './batch';
+import { atomicallyAudited } from './crud-outcome';
+
+/** The reason a queued batch's one entry carries. */
+export const BATCH_QUEUED_REASON = 'admin.batch.queued';
+
+/** The reason it carries when its chunks could not all be queued — the gate's own key. */
+const BATCH_QUEUE_FAILED_REASON = 'admin.error.action-failed';
+
+/**
+ * A queued batch's id, DERIVED from what was asked — who, which action on which resource, these
+ * rows, this input — never drawn at random. The chunk job's idempotency key is
+ * `admin.batch:<batchId>:<index>`, so an operator retrying a request whose third enqueue failed
+ * asks for chunks 0–2 under the keys they already hold, and the queue answers the jobs it has
+ * instead of running those rows twice. The request id is deliberately NOT part of it: a retry is
+ * a new request. Keyed (`keyedFingerprint`), because it is persisted in the queue beside the rows
+ * it was derived from.
+ */
+export const batchIdOf = (
+  input: Pick<AdminBatchInput, 'resource' | 'action' | 'ctx'>,
+  ids: readonly string[],
+  own: Readonly<Record<string, unknown>>,
+): string =>
+  keyedFingerprint(
+    {
+      entity: input.resource.name,
+      action: input.action.name,
+      actor: input.ctx.actor.id,
+      org: input.ctx.actor.orgId ?? null,
+      ids,
+      input: own,
+    },
+    'admin.batch',
+  );
+
+/**
+ * Enqueue `ids` in chunks of `chunk`, answering the job ids. The chunks and the entry ride one
+ * `audit.atomic`: an enqueue joins the caller's transaction, so chunk 3 failing takes chunks 0–2
+ * back out with it. Where nothing can roll back (the memory log), the derived `batchId` is what
+ * makes the retry safe — a chunk already queued is the queue's duplicate, not a second run.
+ */
+export async function queueBatch(
+  input: AdminBatchInput & { readonly enqueue: BatchEnqueue },
+  decision: AdminDecision,
+  chunk: number,
+  ids: readonly string[],
+  own: Readonly<Record<string, unknown>>,
+): Promise<readonly string[]> {
+  const { resource, action, ctx, enqueue } = input;
+  const batchId = batchIdOf(input, ids, own);
+  const { value } = await atomicallyAudited(
+    ctx.audit,
+    {
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: action.name,
+      kind: 'action',
+      entity: resource.name,
+      permission: decision.permission,
+    },
+    { allowed: BATCH_QUEUED_REASON, failed: BATCH_QUEUE_FAILED_REASON },
+    null,
+    async () => {
+      const queued: string[] = [];
+      for (let at = 0; at < ids.length; at += chunk) {
+        const slice = ids.slice(at, at + chunk);
+        const index = at / chunk;
+        queued.push(
+          await enqueue({ resource, action, ids: slice, input: own, ctx, batchId, index }),
+        );
+      }
+      return queued;
+    },
+    // Which job runs handle the chunks: each row's own entry is written when its job reaches it.
+    (queued) => ({
+      entityId: null,
+      diff: [
+        { field: 'rows', before: null, after: ids.length },
+        { field: 'jobs', before: null, after: queued },
+      ],
+    }),
+  );
+  return value;
+}

package/src/batch.ts

@@ -6,9 +6,9 @@ import { finiteCount } from '@ultimat3/core';
 import { expectedQueryLoop } from '@ultimat3/db';
 import { decideAction } from './action-gate';
 import { invokeRowAction } from './action-row';
-import type { AuditEntry } from './audit';
 import type { AdminDecision } from './authz';
 import { runMatching } from './batch-matching';
+import { queueBatch } from './batch-queue';
 import { type CrudCtx, decideOperation } from './crud';
 import { type AdminListRequest, listWhere } from './list-scope';
 import {
@@ -35,9 +35,6 @@ export const MAX_BATCH_ROWS = 200;
  */
 export const MAX_BATCH_QUEUED_ROWS = 1_000;
 
-/** The reason a queued batch's one entry carries. */
-export const BATCH_QUEUED_REASON = 'admin.batch.queued';
-
 /** The reason an action that is not a batch action is refused the batch bar with. */
 export const BATCH_NOT_OFFERED_REASON = 'admin.error.batch-not-offered';
 
@@ -185,29 +182,6 @@ async function select(
   return { ids, remaining };
 }
 
-const queuedEntry = (
-  input: AdminBatchInput,
-  decision: AdminDecision,
-  rows: number,
-  jobs: readonly string[],
-): Promise<AuditEntry> =>
-  input.ctx.audit.append({
-    requestId: input.ctx.requestId,
-    actor: input.ctx.actor,
-    operation: input.action.name,
-    kind: 'action',
-    entity: input.resource.name,
-    entityId: null,
-    permission: decision.permission,
-    outcome: 'allowed',
-    reason: BATCH_QUEUED_REASON,
-    // Which job runs handle the chunks: each row's own entry is written when its job reaches it.
-    diff: [
-      { field: 'rows', before: null, after: rows },
-      { field: 'jobs', before: null, after: jobs },
-    ],
-  });
-
 /**
  * Run `action` over a selection of `resource`'s rows.
  *
@@ -285,22 +259,13 @@ export async function runAdminBatch(input: AdminBatchInput): Promise<AdminBatchA
   };
 
   if (plan !== null && selected.ids.length > plan.threshold && input.enqueue !== undefined) {
-    const batchId = crypto.randomUUID();
-    const jobs: string[] = [];
-    for (let at = 0; at < selected.ids.length; at += plan.chunk) {
-      jobs.push(
-        await input.enqueue({
-          resource,
-          action,
-          ids: selected.ids.slice(at, at + plan.chunk),
-          input: own,
-          ctx,
-          batchId,
-          index: at / plan.chunk,
-        }),
-      );
-    }
-    await queuedEntry(input, decision, selected.ids.length, jobs);
+    const jobs = await queueBatch(
+      { ...input, enqueue: input.enqueue },
+      decision,
+      plan.chunk,
+      selected.ids,
+      own,
+    );
     return {
       ok: true,
       done: 0,