@ultimat3/admin 23.0.0 → 25.0.0

package/src/admin.module.scss

@@ -12,27 +12,125 @@
   background: t.role('bg');
   color: t.role('fg');
 
-  // One column under the `md` rung: the sidebar becomes a block above the screen it navigates.
+  // One column under the `md` rung: the menu bar, then the screen; the sidebar is the panel the
+  // bar opens — or, in an engine with no popovers, a block above the screen it navigates.
   @include t.respond-down('md') {
     grid-template-columns: 1fr;
+    gap: 0;
   }
 }
 
+// Off-screen until focused, then pinned at the inline-start corner. It used to stay visually
+// hidden even WITH focus — the focus ring drew around a 1px box nobody could see.
 .skip {
-  @include t.visually-hidden;
+  @include t.focus-ring;
+
+  position: fixed;
+  z-index: t.z(skip-nav);
+  inset-block-start: t.space(2);
+  inset-inline-start: t.space(2);
+  padding-block: t.space(2);
+  padding-inline: t.space(4);
+  border-radius: t.radius('md');
+  background: t.role('surface-raised');
+  color: t.role('fg-strong');
+  box-shadow: t.shadow(md);
+  text-decoration: none;
 
-  &:focus-visible {
-    @include t.focus-ring;
+  &:not(:focus-visible) {
+    @include t.visually-hidden;
   }
 }
 
+// Hidden unless the engine can open the panel: a menu button that does nothing is worse than the
+// block an engine without popovers still shows.
+.bar {
+  display: none;
+}
+
+// A touch target: this bar exists for a phone.
+.menuButton,
+.close {
+  @include t.focus-ring;
+  @include t.touch-target;
+
+  display: inline-flex;
+  align-items: center;
+  gap: t.space(2);
+  padding-inline: t.space(3);
+  border: 0;
+  border-radius: t.radius('md');
+  background: none;
+  color: t.role('fg-strong');
+  font: inherit;
+  cursor: pointer;
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+.close {
+  display: none;
+  justify-content: center;
+  align-self: flex-end;
+}
+
+// Every `[popover]` gets a UA style — fixed, centred, hidden while closed — so the column undoes
+// each; this box is the sidebar at `md` and up, and at every width where there is no popover.
 .side {
   @include t.surface('surface', 'sm');
   @include t.padding-block(t.space(6));
   @include t.padding-inline(t.space(4));
   @include t.column(t.space(4));
 
+  position: static;
+  inset: auto;
+  inline-size: auto;
+  block-size: auto;
+  margin: 0;
+  color: t.role('fg');
   border-inline-end: t.stroke(hairline) solid t.role('line');
+  overflow: auto;
+}
+
+@include t.respond-down('md') {
+  @supports selector(:popover-open) {
+    .bar {
+      display: flex;
+      align-items: center;
+      padding-block: t.space(1);
+      padding-inline: t.space(2);
+      border-block-end: t.stroke(hairline) solid t.role('line');
+      background: t.role('surface');
+    }
+
+    .side:not(:popover-open) {
+      display: none;
+    }
+
+    // The same edge sheet as `Drawer`'s inline-start side: raised surface, line edge, scrim.
+    .side:popover-open {
+      @include t.scrim-backdrop;
+
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      inset-inline-end: auto;
+      inline-size: min(t.rem(320), calc(100vw - #{t.space(12)}));
+      block-size: 100dvh;
+      max-block-size: 100dvh;
+      border: 0;
+      border-inline-end: t.stroke(hairline) solid t.role('line');
+      border-radius: 0;
+      background: t.role('surface-raised');
+      box-shadow: t.shadow(xl);
+    }
+
+    .close {
+      display: inline-flex;
+    }
+  }
 }
 
 .brand {
@@ -50,8 +148,17 @@
   color: t.role('fg-muted');
 }
 
+// One track that may shrink to the column: an `auto` track is at least its content's min-content
+// width, and a text input's is its `size` — wider than a 256px sidebar's content box, so the box
+// stuck out past the sidebar's edge at every width.
 .search {
   display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  min-inline-size: 0;
+
+  > form {
+    min-inline-size: 0;
+  }
 }
 
 .hidden {
@@ -96,6 +203,13 @@
   &:focus-visible {
     @include t.focus-ring;
   }
+
+  // A touch-target row on a narrow screen, where the link is tapped rather than clicked.
+  @include t.respond-down('md') {
+    display: flex;
+    align-items: center;
+    min-block-size: t.touch(target);
+  }
 }
 
 .main {

package/src/audit-pg.ts

@@ -2,7 +2,7 @@
 // `defineAdmin({ audit: postgresAuditLog() })` names — the memory log is a ring that forgets at
 // every restart, and a row's history that ends at the last deploy is not a history.
 
-import { isUltimateError, uuid } from '@ultimat3/core';
+import { isUltimateError, uuidV7 } from '@ultimat3/core';
 import { type DbClient, db, withTransaction } from '@ultimat3/db';
 import {
   AUDIT_READ_OPERATIONS,
@@ -149,7 +149,7 @@ export interface PostgresAuditLogOptions {
  */
 export function postgresAuditLog(options: PostgresAuditLogOptions = {}): AuditLog {
   const now = options.now ?? ((): Date => new Date());
-  const nextId = options.nextId ?? uuid;
+  const nextId = options.nextId ?? uuidV7;
   const sinks = options.sinks ?? [];
   const reads = options.reads === true;
   // Resolved per statement, never captured: inside `atomic` it is the open transaction.

package/src/audit.ts

@@ -2,12 +2,10 @@
 // If it isn't logged, it didn't happen — so denied and failed attempts are logged too, and
 // there is deliberately no update or delete on this interface.
 
-import { canonicalJson, finiteCount } from '@ultimat3/core';
+import { canonicalJson, finiteCount, REDACTED } from '@ultimat3/core';
 import type { AdminActor, AdminDecision } from './authz';
 import type { AdminRow } from './registry';
 
-export const REDACTED = '[redacted]';
-
 /** Named once, so both refusals below say the same thing about the same call. */
 const SUBJECT = 'memoryAuditLog';
 

package/src/authz.ts

@@ -62,7 +62,7 @@ export interface AdminAuthz {
   decide(query: AdminAuthzQuery): AdminDecision;
 }
 
-export function allowed(
+export function adminAllowed(
   permission: string,
   reason: string,
   trace: readonly string[] = [],
@@ -70,7 +70,7 @@ export function allowed(
   return { allowed: true, permission, reason, trace };
 }
 
-export function denied(
+export function adminDenied(
   permission: string,
   reason: string,
   trace: readonly string[] = [],
@@ -82,7 +82,7 @@ export function denied(
  * Every permission must hold. The first denial wins, and carries its own reason.
  *
  * An EMPTY list is refused, never granted. `permissions[length - 1] ?? ''` used to fall through to
- * `allowed('')`, so a declared-but-empty gate opened for every actor, anonymous included — and the
+ * `adminAllowed('')`, so a declared-but-empty gate opened for every actor, anonymous included — and the
  * decision it returned named no permission at all. `visibleNav` hands an author's
  * `item.permissions` straight here, so `permissions: []` on a nav item was that gate. `pages.ts`
  * already refuses an empty page list at declaration time (`X_ADMIN_PAGE_UNGUARDED`); this is the
@@ -96,7 +96,7 @@ export function decideAll(
   subject?: AdminSubject,
 ): AdminDecision {
   if (permissions.length === 0) {
-    return denied('', 'admin.policy.none-declared', [
+    return adminDenied('', 'admin.policy.none-declared', [
       'no permission was declared for this surface, so there is nothing to satisfy',
     ]);
   }
@@ -107,10 +107,10 @@ export function decideAll(
     );
     trace.push(`${permission}: ${decision.allowed ? 'allow' : 'deny'} (${decision.reason})`);
     if (!decision.allowed)
-      return denied(permission, decision.reason, [...trace, ...decision.trace]);
+      return adminDenied(permission, decision.reason, [...trace, ...decision.trace]);
   }
   const last = permissions[permissions.length - 1] ?? '';
-  return allowed(last, 'admin.policy.all-granted', trace);
+  return adminAllowed(last, 'admin.policy.all-granted', trace);
 }
 
 export function isAllowed(
@@ -167,8 +167,8 @@ export function staticAuthz(granted: readonly string[]): AdminAuthz {
   return {
     decide({ permission }): AdminDecision {
       return set.has(permission)
-        ? allowed(permission, 'admin.policy.granted', [`static: ${permission} in grant list`])
-        : denied(permission, 'admin.policy.not-granted', [
+        ? adminAllowed(permission, 'admin.policy.granted', [`static: ${permission} in grant list`])
+        : adminDenied(permission, 'admin.policy.not-granted', [
             `static: ${permission} not in [${[...set].join(', ')}]`,
           ]);
     },

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

@@ -4,19 +4,14 @@
 
 import { finiteCount } from '@ultimat3/core';
 import { expectedQueryLoop } from '@ultimat3/db';
-import { decideAction } from './action-gate';
+import { adminPermissionForAction, 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 {
-  ADMIN_DESTROY,
-  ADMIN_WRITE,
-  CONFIRMATION_REQUIRED_REASON,
-  confirmationToken,
-} from './permissions';
+import { ADMIN_DESTROY, CONFIRMATION_REQUIRED_REASON, confirmationToken } from './permissions';
 import type { AdminAction, AdminFilter } from './registry';
 import { rowId } from './registry';
 import { type AdminResource, repoOf } from './resource';
@@ -35,9 +30,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 +177,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.
  *
@@ -228,7 +197,7 @@ export async function runAdminBatch(input: AdminBatchInput): Promise<AdminBatchA
   if (action.batch === undefined) {
     return denied({
       allowed: false,
-      permission: action.destructive === true ? ADMIN_DESTROY : ADMIN_WRITE,
+      permission: adminPermissionForAction(action),
       reason: BATCH_NOT_OFFERED_REASON,
       trace: [`batch: ${action.name} does not declare batch`],
     });
@@ -285,22 +254,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,

package/src/crud-input.ts

@@ -2,7 +2,8 @@
 // tenant column taken out of the caller's hands, and the audit diff of what the write changed.
 // Pure over the resource — `crud.ts` decides and writes, this file only shapes the input.
 
-import { type AuditFieldDiff, diffRows, REDACTED } from './audit';
+import { REDACTED } from '@ultimat3/core';
+import { type AuditFieldDiff, diffRows } from './audit';
 import type { CrudCtx } from './crud';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';