@ultimat3/admin 31.9.0 → 31.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "31.9.0",
+  "version": "31.10.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "keywords": [
     "ultimate",
@@ -46,21 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "31.9.0",
-    "@ultimat3/ai": "31.9.0",
-    "@ultimat3/cache": "31.9.0",
-    "@ultimat3/core": "31.9.0",
-    "@ultimat3/db": "31.9.0",
-    "@ultimat3/entity": "31.9.0",
-    "@ultimat3/http": "31.9.0",
-    "@ultimat3/i18n": "31.9.0",
-    "@ultimat3/jobs": "31.9.0",
-    "@ultimat3/mcp": "31.9.0",
-    "@ultimat3/money": "31.9.0",
-    "@ultimat3/policy": "31.9.0",
-    "@ultimat3/query": "31.9.0",
-    "@ultimat3/render": "31.9.0",
-    "@ultimat3/schema": "31.9.0",
-    "@ultimat3/ui": "31.9.0"
+    "@ultimat3/action": "31.10.0",
+    "@ultimat3/ai": "31.10.0",
+    "@ultimat3/cache": "31.10.0",
+    "@ultimat3/core": "31.10.0",
+    "@ultimat3/db": "31.10.0",
+    "@ultimat3/entity": "31.10.0",
+    "@ultimat3/http": "31.10.0",
+    "@ultimat3/i18n": "31.10.0",
+    "@ultimat3/jobs": "31.10.0",
+    "@ultimat3/mcp": "31.10.0",
+    "@ultimat3/money": "31.10.0",
+    "@ultimat3/policy": "31.10.0",
+    "@ultimat3/query": "31.10.0",
+    "@ultimat3/render": "31.10.0",
+    "@ultimat3/schema": "31.10.0",
+    "@ultimat3/ui": "31.10.0"
   }
 }

package/src/crud-outcome.ts

@@ -2,6 +2,7 @@
 // row that was not there, a repo that threw. Each leaves its entry and answers the result the
 // caller renders — so `crud.ts` reads as the five steps of each operation and nothing else.
 
+import { isUltimateError } from '@ultimat3/core';
 import {
   type AuditDraft,
   type AuditEntry,
@@ -73,14 +74,18 @@ export type AuditedEntry = Pick<
  * say `failed` for an action that had committed, and an operator re-ran it.
  *
  * The `failed` entry is written OUTSIDE, after the rollback — inside, it would be rolled back with
- * the write it reports. Nothing about the thrown value is read or rendered (a `catch` binding holds
+ * the write it reports. Nothing about the thrown value is rendered (a `catch` binding holds
  * whatever an app threw, and `String()` of a prototype-less object throws from inside the block
- * that owes the auditor its entry); the caller gets it UNCHANGED, and an audit reason is a key.
+ * that owes the auditor its entry); the caller gets it UNCHANGED, and an audit reason is a key —
+ * one `reasons.failed` may pick by asking the TOTAL `isUltimateError` for a code, nothing more.
  */
 export async function atomicallyAudited<T>(
   audit: AuditLog,
   entry: AuditedEntry,
-  reasons: { readonly allowed: string; readonly failed: string },
+  reasons: {
+    readonly allowed: string;
+    readonly failed: string | ((error: unknown) => string);
+  },
   /** The id of the row the write addresses, for the `failed` entry: `null` for a set or a create. */
   entityId: string | null,
   write: () => Promise<T>,
@@ -89,6 +94,8 @@ export async function atomicallyAudited<T>(
     readonly entityId: string | null;
     readonly diff: readonly AuditFieldDiff[];
   },
+  /** Handed the `failed` entry before the error is rethrown — `auditedUpdate` answers with it. */
+  failedWith?: (entry: AuditEntry) => void,
 ): Promise<{ readonly value: T; readonly audit: AuditEntry }> {
   try {
     return await audit.atomic(async () => {
@@ -102,7 +109,9 @@ export async function atomicallyAudited<T>(
       return { value, audit: appended };
     });
   } catch (error) {
-    await audit.append({ ...entry, entityId, outcome: 'failed', reason: reasons.failed, diff: [] });
+    const reason = typeof reasons.failed === 'string' ? reasons.failed : reasons.failed(error);
+    const failed = await audit.append({ ...entry, entityId, outcome: 'failed', reason, diff: [] });
+    failedWith?.(failed);
     throw error;
   }
 }
@@ -139,6 +148,59 @@ export function auditedWrite<T>(
   );
 }
 
+/** The entity's version lock refused the write: the row moved between the admin's read and it. */
+const lostRace = (error: unknown): boolean =>
+  isUltimateError(error) && error.code === 'X_ENTITY_STALE';
+
+/**
+ * `auditedWrite` for an update. A write the entity's declared lock refuses (`X_ENTITY_STALE`) is
+ * the same conflict the form's `_version` check answers, only later: one `failed` entry keyed
+ * `admin.error.row-changed`, answered as `stale` rather than thrown. Anything else rethrows.
+ */
+export async function auditedUpdate<T>(
+  resource: { readonly name: string },
+  ctx: CrudCtx,
+  entityId: string,
+  decision: AdminDecision,
+  write: () => Promise<T>,
+  written: (value: T) => {
+    readonly entityId: string | null;
+    readonly diff: readonly AuditFieldDiff[];
+  },
+): Promise<
+  | { readonly stale: false; readonly value: T; readonly audit: AuditEntry }
+  | { readonly stale: true; readonly audit: AuditEntry }
+> {
+  let refused: AuditEntry | undefined;
+  try {
+    const done = await atomicallyAudited(
+      ctx.audit,
+      {
+        requestId: ctx.requestId,
+        actor: ctx.actor,
+        operation: 'update',
+        kind: 'operation',
+        entity: resource.name,
+        permission: decision.permission,
+      },
+      {
+        allowed: decision.reason,
+        failed: (error) => (lostRace(error) ? ROW_CHANGED_REASON : WRITE_FAILED_REASON),
+      },
+      entityId,
+      write,
+      written,
+      (entry) => {
+        refused = entry;
+      },
+    );
+    return { stale: false, ...done };
+  } catch (error) {
+    if (refused !== undefined && lostRace(error)) return { stale: true, audit: refused };
+    throw error;
+  }
+}
+
 /** The key a write to a row that is not there is logged with. */
 const ROW_MISSING_REASON = 'admin.error.row-missing';
 

package/src/crud.ts

@@ -5,7 +5,15 @@
 import type { AuditEntry, AuditLog } from './audit';
 import { type AdminActor, type AdminAuthz, type AdminDecision, decideAll } from './authz';
 import { onlyFor, rowDiff, splitSecrets, withoutTenant, withTenant } from './crud-input';
-import { auditedWrite, deniedEntry, invalid, missingRow, refuse, staleRow } from './crud-outcome';
+import {
+  auditedUpdate,
+  auditedWrite,
+  deniedEntry,
+  invalid,
+  missingRow,
+  refuse,
+  staleRow,
+} from './crud-outcome';
 import { type AdminListRequest, findRow, listWhere } from './list-scope';
 import { type AdminPage, fetchPage } from './pagination';
 import {
@@ -337,19 +345,40 @@ export async function adminUpdate<Row extends AdminRow>(
         .map((key) => [key, parsed.value[key]]),
     ),
     ...secrets,
+    // A declared lock: the version the admin READ, which the form's `_version` just matched — so a
+    // write landing after that read is the entity's X_ENTITY_STALE, answered `stale` below.
+    ...versionRead(resource, before, submittedKeys),
   };
-  const { value: after, audit } = await auditedWrite(
+  const outcome = await auditedUpdate(
     resource,
-    'update',
     ctx,
     id,
     written,
     () => repo.update(id, validatedPatch),
     (changed) => ({ entityId: id, diff: rowDiff(resource, before, changed, secrets) }),
   );
-  return { ok: true, row: after, audit };
+  if (!outcome.stale) return { ok: true, row: outcome.value, audit: outcome.audit };
+  const current = (await findRow(resource, ctx.actor, id)) ?? before;
+  return {
+    ok: false,
+    kind: 'stale',
+    row: current,
+    version: rowVersion(current),
+    audit: outcome.audit,
+  };
 }
 
+/** `{ [lock]: before[lock] }` for an entity declaring `version:`, unless the caller named it. */
+const versionRead = (
+  resource: AdminResource,
+  before: AdminRow,
+  submitted: readonly string[],
+): Readonly<Record<string, unknown>> => {
+  const lock = resource.entity.$version;
+  if (typeof lock !== 'string' || submitted.includes(lock)) return {};
+  return { [lock]: before[lock] };
+};
+
 /** Destructive: the caller must echo `confirmationToken(entity, id)` or nothing happens. */
 export async function adminDestroy<Row extends AdminRow>(
   resource: AdminResource<Row>,

package/src/mcp-dispatch.ts

@@ -213,7 +213,8 @@ function crudResult(result: CrudResult<AdminRow>): AdminToolResult {
   if (result.kind === 'missing') {
     return { ok: false, error: 'X_ADMIN_INVALID', reason: 'no row has that id' };
   }
-  // Reached only by a caller that sent a version; the update tool sends none.
+  // The update tool sends no form version: reached when an entity's declared lock refused the
+  // write (X_ENTITY_STALE) because another write landed after this call read the row.
   if (result.kind === 'stale') {
     return { ok: false, error: 'X_ADMIN_INVALID', reason: 'the row changed since it was read' };
   }

package/src/registry.ts

@@ -90,6 +90,11 @@ export interface AdminEntity {
   readonly $viewQuery?: { readonly materialized: boolean } | null;
   /** `entity({ readOnly })`'s reason, `null` on a table the app writes: reads alone, as a view. */
   readonly $readOnly?: string | null;
+  /**
+   * `entity({ version })`'s lock property, `null` without one. Optional only because a hand-built
+   * fixture has none: never a form input, and every update carries the version the admin read.
+   */
+  readonly $version?: string | null;
   /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
   $describe(): AdminEntityDescription;
 }

package/src/resource-fields.ts

@@ -62,6 +62,9 @@ export function deriveField(
   // The handle scopes every read and write by this column, so the acting actor's tenant is the
   // only value it can hold: it is not an input, not a list column, and not a filter.
   const tenant = entity.$tenantColumn === name;
+  // The declared lock counts writes: the update carries the version it read (`crud.ts`), so an
+  // operator never types one — a form or MCP input for it would be a way round the lock.
+  const version = entity.$version === name;
   const filterKind = tenant ? undefined : filterKindFor(type, column);
 
   return {
@@ -71,7 +74,7 @@ export function deriveField(
     widget,
     labelKey: override?.labelKey ?? `admin.${entity.$name}.field.${name}`,
     required: override?.required ?? (!column.nullable && !generated && !tenant),
-    readOnly: override?.readOnly ?? (generated || tenant),
+    readOnly: override?.readOnly ?? (generated || tenant || version),
     sensitive,
     inList: override?.inList ?? (listable(type) && !sensitive && !tenant),
     filterable: filterKind !== undefined && (override?.filterable ?? filterable(type, column)),