@ultimat3/admin 23.0.0 → 24.0.0

package/src/crud-outcome.ts

@@ -2,12 +2,19 @@
 // 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 { type AuditEntry, type AuditFieldDiff, deniedDraft } from './audit';
+import {
+  type AuditDraft,
+  type AuditEntry,
+  type AuditFieldDiff,
+  type AuditLog,
+  deniedDraft,
+} from './audit';
 import type { AdminDecision } from './authz';
 import type { CrudCtx, CrudResult } from './crud';
 import type { AdminOperation } from './permissions';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
+import { ROW_CHANGED_REASON } from './row-version';
 import type { ValidationIssue } from './validate';
 
 export const deniedEntry = (
@@ -47,31 +54,35 @@ export async function refuse<Row extends AdminRow>(
 /** The reason on a `failed` entry. A key, never the database's message. */
 const WRITE_FAILED_REASON = 'admin.audit.write-failed';
 
+/** What every entry of one audited write shares: who, what, on which table, under which grant. */
+export type AuditedEntry = Pick<
+  AuditDraft,
+  'requestId' | 'actor' | 'operation' | 'kind' | 'entity' | 'permission'
+>;
+
 /**
- * Run a repo WRITE and append its entry — as one unit where the log can make it one — and leave a
- * `failed` entry behind if either throws.
- *
- * `AuditOutcome` has declared a `failed` member all along and this file emitted it in exactly one
- * place — `invalid()`, for a VALIDATION issue. A constraint violation, a statement that timed out
- * after committing, a connection dropped mid-write: each left no entry at all, which is the case
- * an auditor opens the log for. Both siblings already do this and each states the rule
- * (`search.ts`, `action-gate.ts`).
+ * Run a WRITE and append its entry as one unit where the log can make it one, and leave a `failed`
+ * entry behind if either throws — the one shape for a CRUD write, an action's handler, a set-based
+ * batch and a queued one.
  *
  * A mutation cannot append BEFORE the call the way a read does — that would record a write which
  * may never have happened. So the write and its entry go inside `audit.atomic`: a durable log
  * opens a transaction, so a row never changes without the entry naming who changed it, and an
- * entry never describes a write that rolled back. The `failed` entry is written OUTSIDE it, after
- * the rollback — inside, it would be rolled back with the write it reports. Nothing about the
- * thrown value is read or rendered; the caller owns it, and an audit reason is a key.
+ * entry never describes a write that rolled back. A sink that throws on the `allowed` entry rolls
+ * the write back with it; the log then says `failed`, and so does the caller's error — it used to
+ * 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
+ * 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.
  */
-export async function auditedWrite<T>(
-  // Only the NAME is read, so this stays invariance-free: `AdminResource<Row>` at four call
-  // sites would need the generic threaded through for nothing.
-  resource: { readonly name: string },
-  op: AdminOperation,
-  ctx: CrudCtx,
+export async function atomicallyAudited<T>(
+  audit: AuditLog,
+  entry: AuditedEntry,
+  reasons: { readonly allowed: string; readonly failed: string },
+  /** The id of the row the write addresses, for the `failed` entry: `null` for a set or a create. */
   entityId: string | null,
-  decision: AdminDecision,
   write: () => Promise<T>,
   /** The diff of what the write did, and the id of the row it left — known only afterwards. */
   written: (value: T) => {
@@ -79,37 +90,55 @@ export async function auditedWrite<T>(
     readonly diff: readonly AuditFieldDiff[];
   },
 ): Promise<{ readonly value: T; readonly audit: AuditEntry }> {
-  const entry = {
-    requestId: ctx.requestId,
-    actor: ctx.actor,
-    operation: op,
-    kind: 'operation',
-    entity: resource.name,
-    permission: decision.permission,
-  } as const;
   try {
-    return await ctx.audit.atomic(async () => {
+    return await audit.atomic(async () => {
       const value = await write();
-      const audit = await ctx.audit.append({
+      const appended = await audit.append({
         ...entry,
         ...written(value),
         outcome: 'allowed',
-        reason: decision.reason,
+        reason: reasons.allowed,
       });
-      return { value, audit };
+      return { value, audit: appended };
     });
   } catch (error) {
-    await ctx.audit.append({
-      ...entry,
-      entityId,
-      outcome: 'failed',
-      reason: WRITE_FAILED_REASON,
-      diff: [],
-    });
+    await audit.append({ ...entry, entityId, outcome: 'failed', reason: reasons.failed, diff: [] });
     throw error;
   }
 }
 
+/** A repo WRITE of one CRUD operation, through `atomicallyAudited`. */
+export function auditedWrite<T>(
+  // Only the NAME is read, so this stays invariance-free: `AdminResource<Row>` at four call
+  // sites would need the generic threaded through for nothing.
+  resource: { readonly name: string },
+  op: AdminOperation,
+  ctx: CrudCtx,
+  entityId: string | null,
+  decision: AdminDecision,
+  write: () => Promise<T>,
+  written: (value: T) => {
+    readonly entityId: string | null;
+    readonly diff: readonly AuditFieldDiff[];
+  },
+): Promise<{ readonly value: T; readonly audit: AuditEntry }> {
+  return atomicallyAudited(
+    ctx.audit,
+    {
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: op,
+      kind: 'operation',
+      entity: resource.name,
+      permission: decision.permission,
+    },
+    { allowed: decision.reason, failed: WRITE_FAILED_REASON },
+    entityId,
+    write,
+    written,
+  );
+}
+
 /** The key a write to a row that is not there is logged with. */
 const ROW_MISSING_REASON = 'admin.error.row-missing';
 
@@ -138,6 +167,35 @@ export async function missingRow<Row extends AdminRow>(
   };
 }
 
+/** An update against a version the row no longer has — `crud.ts`'s optimistic check. */
+export async function staleRow<Row extends AdminRow>(
+  resource: AdminResource<Row>,
+  ctx: CrudCtx,
+  id: string,
+  decision: AdminDecision,
+  row: Row,
+  version: string,
+): Promise<CrudResult<Row>> {
+  return {
+    ok: false,
+    kind: 'stale',
+    row,
+    version,
+    audit: await ctx.audit.append({
+      requestId: ctx.requestId,
+      actor: ctx.actor,
+      operation: 'update',
+      kind: 'operation',
+      entity: resource.name,
+      entityId: id,
+      permission: decision.permission,
+      outcome: 'failed',
+      reason: ROW_CHANGED_REASON,
+      diff: [],
+    }),
+  };
+}
+
 export async function invalid<Row extends AdminRow>(
   resource: AdminResource<Row>,
   op: AdminOperation,

package/src/crud.ts

@@ -5,7 +5,7 @@
 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 } from './crud-outcome';
+import { auditedWrite, deniedEntry, invalid, missingRow, refuse, staleRow } from './crud-outcome';
 import { type AdminListRequest, findRow, listWhere } from './list-scope';
 import { type AdminPage, fetchPage } from './pagination';
 import {
@@ -20,6 +20,7 @@ import type { AdminRow } from './registry';
 import { type AdminResource, repoOf } from './resource';
 import type { AdminScope } from './resource-list';
 import { outOfScopeDecision, writeOutsideScope } from './row-scope-write';
+import { rowVersion } from './row-version';
 import { type ValidationIssue, validateInput } from './validate';
 
 export interface CrudCtx {
@@ -49,7 +50,28 @@ export type CrudResult<Row extends AdminRow> =
    * actor's row scope, which are one answer on purpose. Nothing was written; the attempt is on
    * the log as `failed`, like every other write that did not happen.
    */
-  | { readonly ok: false; readonly kind: 'missing'; readonly audit: AuditEntry };
+  | { readonly ok: false; readonly kind: 'missing'; readonly audit: AuditEntry }
+  /**
+   * An update against a `version` the row no longer has: somebody wrote it after the form was
+   * rendered. Nothing was written; the attempt is on the log as `failed`
+   * (`admin.error.row-changed`), and `row` is the row as it is NOW — what a re-render shows.
+   */
+  | {
+      readonly ok: false;
+      readonly kind: 'stale';
+      readonly row: Row;
+      readonly version: string;
+      readonly audit: AuditEntry;
+    };
+
+export interface AdminUpdateOptions {
+  /**
+   * `rowVersion()` of the row the caller was shown — the edit form posts it as `_version`. Given,
+   * a row that has changed since is refused (`kind: 'stale'`) instead of overwritten with the
+   * stale copy. Omitted (an MCP call, a script), the write is against the row as it is now.
+   */
+  readonly version?: string;
+}
 
 export type ListResult<Row extends AdminRow> =
   | {
@@ -89,6 +111,12 @@ export function decideOperation(
    * pair was the only gate on a single row.
    */
   row?: AdminRow | null,
+  /**
+   * The validated values a create or an update WRITES — the row as the write leaves it. A rule
+   * over what is written ("nobody files an invoice as paid") reads it as `input`; absent on every
+   * surface that writes nothing.
+   */
+  input?: Readonly<Record<string, unknown>>,
 ): AdminDecision {
   // First, before any grant is consulted: an operation the resource does not OFFER is refused for
   // everyone. `canOperate` checked this for the nav, the buttons and the MCP tools, and the three
@@ -106,6 +134,7 @@ export function decideOperation(
     entity: resource.name,
     ...(id === undefined ? {} : { id }),
     ...(row === undefined ? {} : { row }),
+    ...(input === undefined ? {} : { input }),
   });
 }
 
@@ -231,13 +260,17 @@ export async function adminCreate<Row extends AdminRow>(
     const permission = entityPermissionFor(resource.permission, 'create');
     return refuse(resource, 'create', ctx, outOfScopeDecision(permission, outside), null);
   }
+  // Decided again on what is WRITTEN: the first decision had no values to read, and a rule over
+  // them is the one an ownership or a state rule on a create is.
+  const written = decideOperation(resource, 'create', ctx, undefined, undefined, parsed.value);
+  if (!written.allowed) return refuse(resource, 'create', ctx, written, null);
 
   const { value: row, audit } = await auditedWrite(
     resource,
     'create',
     ctx,
     null,
-    decision,
+    written,
     () => repoOf(resource).create({ ...parsed.value, ...secrets }),
     (made) => ({
       entityId: String(made[resource.idField] ?? ''),
@@ -252,6 +285,7 @@ export async function adminUpdate<Row extends AdminRow>(
   ctx: CrudCtx,
   id: string,
   patch: Readonly<Record<string, unknown>>,
+  options: AdminUpdateOptions = {},
 ): Promise<CrudResult<Row>> {
   // `before` was already loaded here, just after the guard rather than before it — so the rule
   // that decides whether this actor may touch THIS row never saw the row.
@@ -260,6 +294,12 @@ export async function adminUpdate<Row extends AdminRow>(
   const decision = decideOperation(resource, 'update', ctx, id, before);
   if (!decision.allowed) return refuse(resource, 'update', ctx, decision, id);
   if (before === null) return missingRow(resource, 'update', ctx, id, decision);
+  // Optimistic concurrency: the patch was composed against what the caller was SHOWN, and a merge
+  // onto a row that has moved on writes their stale copy of every field they posted.
+  const now = rowVersion(before);
+  if (options.version !== undefined && options.version !== now) {
+    return staleRow(resource, ctx, id, decision, before, now);
+  }
 
   // `{ ...before }` carries no sealed value — a row's sealed properties are non-enumerable — and
   // `$schema` has no member for one, so the merged object is exactly what the schema describes.
@@ -286,6 +326,10 @@ export async function adminUpdate<Row extends AdminRow>(
     const permission = entityPermissionFor(resource.permission, 'update');
     return refuse(resource, 'update', ctx, outOfScopeDecision(permission, outside), id);
   }
+  // Decided again with the row before AND the row the write leaves — a rule over the values an
+  // operator is about to write ("not to paid", "not to another owner") reads `input`.
+  const written = decideOperation(resource, 'update', ctx, id, before, parsed.value);
+  if (!written.allowed) return refuse(resource, 'update', ctx, written, id);
   const validatedPatch: Readonly<Record<string, unknown>> = {
     ...Object.fromEntries(
       submittedKeys
@@ -299,7 +343,7 @@ export async function adminUpdate<Row extends AdminRow>(
     'update',
     ctx,
     id,
-    decision,
+    written,
     () => repo.update(id, validatedPatch),
     (changed) => ({ entityId: id, diff: rowDiff(resource, before, changed, secrets) }),
   );

package/src/dev/data.ts

@@ -155,12 +155,9 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         hydrate: route.hydrate,
         // A descriptor has no `handler`: the FILE is what names the row.
         handler: route.file,
-        // Two flat fields on the descriptor, one nested bag on the fact — the panel's budget
-        // check reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
-        budget: {
-          ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
-          ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
-        },
+        // A flat field on the descriptor, a nested bag on the fact — the panel's budget check
+        // reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
+        budget: route.budgetJs === null ? {} : { js: route.budgetJs },
         // `revalidateTags`, already flattened to keys — never `revalidate.tags`, a shape the
         // descriptor does not have and which answered `[]` for every ISR route in the app.
         revalidateTags: route.revalidateTags,

package/src/dev/facts.ts

@@ -20,7 +20,7 @@ export interface RouteFact {
   readonly hydrate: string;
   /** The route's source file: what names the row. A descriptor publishes no handler. */
   readonly handler: string;
-  readonly budget: { readonly js?: string; readonly lcp?: number };
+  readonly budget: { readonly js?: string };
   readonly revalidateTags: readonly string[];
   /**
    * `RouteDescriptor.mount` — who mounted a route no surface file declares (`defineAdmin`), and

package/src/dev/index.ts

@@ -48,3 +48,4 @@ export {
   devDashboard,
   devShellStyle,
 } from './server';
+export { DEV_SQL_MAX_ROWS, readOnlySql } from './sql-runner';

package/src/dev/panel-cache.ts

@@ -2,6 +2,7 @@
 // Kills: "why is this page still stale?" — the tag graph, and the invalidation log showing
 // what busted what.
 
+import { DevSourceUnavailableError } from '../errors';
 import type { CacheEdgeFact, InvalidationFact } from './facts';
 import type { DevPanel } from './panel';
 
@@ -23,11 +24,15 @@ export const cachePanel: DevPanel<CachePanelData> = {
   questionKey: 'dev.panel.cache.question',
   async data(sources): Promise<CachePanelData> {
     const graph = await sources.cacheGraph();
-    // The invalidation log needs a running process that has served a write; the graph alone
-    // is still worth showing.
+    // The invalidation log needs a running process that has served a write; the graph alone is
+    // still worth showing when it is NOT WIRED — and only then. A log that is wired and failed is
+    // a diagnostic, not "no invalidations yet".
     const invalidations = await sources
       .invalidations()
-      .catch((): readonly InvalidationFact[] => []);
+      .catch((error: unknown): readonly InvalidationFact[] => {
+        if (!(error instanceof DevSourceUnavailableError)) throw error;
+        return [];
+      });
 
     const busted = new Set(invalidations.flatMap((event) => event.busted));
     // A `Map`, then `Object.fromEntries` — never `count[key] = (count[key] ?? 0) + 1` on a plain

package/src/dev/panel-timeline.ts

@@ -3,6 +3,7 @@
 // calls, and policy decisions on one axis, with the N+1 already counted for you — counted by
 // `x dev`'s statement ledger and read here through `statementLoops()`, never re-derived.
 
+import { DevSourceUnavailableError } from '../errors';
 import type { RequestTrace, SpanKind, StatementLoopFact, TimelineSpan } from './facts';
 import type { DevPanel } from './panel';
 
@@ -68,8 +69,12 @@ export const timelinePanel: DevPanel<TimelinePanelData> = {
       (wanted === null ? traces[0] : traces.find((trace) => trace.requestId === wanted)) ?? null;
     // Degrade rather than reject, as `panel-live.ts` does for `subscribers`: a host with traces
     // but no detector installed must still get its flamegraph. `null` carries that difference —
-    // "nobody counted" is not "counted, and this request was clean".
-    const loops = await sources.statementLoops().catch((): null => null);
+    // "nobody counted" is not "counted, and this request was clean". Only for the error that MEANS
+    // unwired: a detector that ran and failed is a diagnostic, never "no detector".
+    const loops = await sources.statementLoops().catch((error: unknown): null => {
+      if (!(error instanceof DevSourceUnavailableError)) throw error;
+      return null;
+    });
 
     const totalsByKind: Record<string, number> = {};
     const sqlCounts = new Map<string, number>();

package/src/dev/panel.ts

@@ -2,7 +2,7 @@
 // draws — and because `data()` returns plain JSON, `--json` and the rendered tab are the
 // same facts by construction.
 
-import { renderThrowable, stringField } from '@ultimat3/core';
+import { InternalError, renderThrowable, stringField } from '@ultimat3/core';
 import type { DevSources } from './facts';
 
 export interface DevPanel<Data = unknown> {
@@ -53,7 +53,9 @@ export async function panelPayload(
       panel: panel.key,
       ok: false,
       error: {
-        code: stringField(error, 'code') ?? 'X_NOT_IMPLEMENTED',
+        // Core's code for a failure nothing classified. `X_NOT_IMPLEMENTED` was here, and it told
+        // the reader a feature was missing when a source had thrown something with no code at all.
+        code: stringField(error, 'code') ?? InternalError.code,
         cause: stringField(error, 'cause') ?? renderThrowable(error),
         fix: stringField(error, 'fix') ?? 'x dev --help',
       },

package/src/dev/server.ts

@@ -4,7 +4,7 @@
 
 // Type-only, so it is erased and the 46-component barrel stays out of the mount graph — the
 // values arrive through the dynamic `import()` in `devShellStyle()`, same reason as `data.ts`.
-import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { DEFAULT_ENVIRONMENT, escapeHtml, tryResolveEnvironment } from '@ultimat3/core';
 import { FRAMEWORK_CATALOG_LOCALE, translatorFor } from '@ultimat3/i18n';
 import type { ColorRole } from '@ultimat3/ui';
 import { DevDashboardInProdError } from '../errors';
@@ -85,9 +85,6 @@ const jsonResponse = (body: unknown, status = 200): Response =>
     headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
   });
 
-const escapeHtml = (value: string): string =>
-  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-
 /** The six roles /_x paints with. `--x-*` is the admin's namespace; the values are ui's. */
 const SHELL_ROLES = [
   'bg',

package/src/dev/sql-runner.ts

@@ -0,0 +1,31 @@
+// The `/_x` DB panel's statement, RUN: inside `readOnlyQuery` — its own `BEGIN READ ONLY`
+// transaction, a statement timeout and a row ceiling — never through the app's plain `db.query`.
+// A host wires `runSql: readOnlySql(client)`; the guard upstream decides what reaches it.
+
+import { type DbClient, readOnlyQuery } from '@ultimat3/db';
+import type { SqlResult } from './facts';
+
+/**
+ * The most rows the panel asks the server for. It draws a grid, not an export: a cursor fetches
+ * this many and the rest of a `select * from events` is never materialised in the dev process.
+ */
+export const DEV_SQL_MAX_ROWS = 500;
+
+/**
+ * The runner a `/_x` host hands the DB panel. `assertReadOnlyQuery` (`panel-db.ts`) is the parse
+ * guard; this is the SERVER saying no: a statement the guard let through that writes, locks or
+ * runs away still meets a read-only transaction that always rolls back, with the app's own
+ * credentials and no way to commit. Columns are the first row's keys — the driver hands objects.
+ */
+export function readOnlySql(client: DbClient): (sql: string) => Promise<SqlResult> {
+  return async (sql) => {
+    const started = performance.now();
+    const { rows } = await readOnlyQuery<Readonly<Record<string, unknown>>>(sql, {
+      client,
+      maxRows: DEV_SQL_MAX_ROWS,
+    });
+    const elapsedMs = Math.round(performance.now() - started);
+    const columns = Object.keys(rows[0] ?? {});
+    return { columns, rows: rows.map((row) => columns.map((column) => row[column])), elapsedMs };
+  };
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 // The X_* codes owned by @ultimat3/admin. Every one names the exact edit that fixes it,
 // because the two dashboards fail at boot (bad registry, bad mount) where an agent has no
 // stack trace to reason from — only the message.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { NotImplementedError, registerErrorCodes, UltimateError } from '@ultimat3/core';
 
 /** Codes this package declares and owns. */
 export const ADMIN_OWNED_ERROR_CODES = [
@@ -32,8 +32,8 @@ export const ADMIN_OWNED_ERROR_CODES = [
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `DevSourceUnavailableError` throws it; this package
- * neither titles nor registers it, because the owner's title is the only one that may exist.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. `DevSourceUnavailableError` IS core's
+ * `NotImplementedError`, narrowed; this package neither constructs, titles nor registers the code, because the owner's title is the only one that may exist.
  */
 export const ADMIN_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
 
@@ -254,11 +254,15 @@ export class AdminPagePathInvalidError extends UltimateError {
  * A `/_x` panel needs a fact the framework cannot introspect on its own — request traces,
  * caught mail, the read-only SQL tool, the committed manifest. Thrown instead of drawing an
  * empty panel, because an empty panel reads as "nothing happened".
+ *
+ * Core's NotImplementedError and not a sibling of it: core is the one constructor of the code.
+ * A class of its own all the same, because a panel degrades on "this source is not wired" and on
+ * nothing wider — a wired source whose driver answers X_NOT_IMPLEMENTED is a diagnostic, not an
+ * unwired tab (dev/panel-degrade.test.ts).
  */
-export class DevSourceUnavailableError extends UltimateError {
+export class DevSourceUnavailableError extends NotImplementedError {
   constructor(input: { source: string; panel: string; wiring?: string }) {
     super({
-      code: 'X_NOT_IMPLEMENTED',
       cause: `the /_x ${input.panel} panel needs the "${input.source}" source, which is not wired in this process`,
       // `wiring`, when supplied, replaces the whole `defaultDevSources(...)` argument text —
       // the default `hooks: { <source> }` phrasing is only valid when the source really is a

package/src/form-decode.ts

@@ -6,6 +6,7 @@
 // that was typed, so the schema refuses it in its own words against the field that carried it.
 
 import type { AdminField } from './fields';
+import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
 
 /** The posted name of a money field's currency, beside the minor-unit amount under the field's own. */
@@ -13,6 +14,39 @@ export const currencyFieldOf = (field: string): string => `${field}.currency`;
 
 type Posted = Readonly<Record<string, unknown>>;
 
+/**
+ * What a date control is RENDERED with: `<input type="date">` wants `YYYY-MM-DD`, `datetime-local`
+ * wants `YYYY-MM-DDTHH:mm`. One function for the widget that draws the box and for the decode that
+ * reads it back, so "the operator left it as it was" is a comparison of one text with itself.
+ */
+export const datetimeInputValue = (iso: string, precision: 'date' | 'instant'): string =>
+  iso.slice(0, precision === 'date' ? 10 : 16);
+
+const isoOf = (value: unknown): string | undefined =>
+  value instanceof Date
+    ? Number.isNaN(value.getTime())
+      ? undefined
+      : value.toISOString()
+    : typeof value === 'string'
+      ? value
+      : undefined;
+
+/**
+ * An instant posted back as the box rendered it. `datetime-local` holds minutes, so writing what
+ * came back turned `10:20:45.123` into `10:20:00.000` on every edit of ANY field — a change nobody
+ * made, recorded in the audit diff as theirs. Such a field is left out of the patch and the stored
+ * instant stands. A calendar date carries every digit it has and is never in this position.
+ */
+const untouchedInstant = (
+  field: AdminField,
+  raw: string | undefined,
+  before: AdminRow,
+): boolean => {
+  if (field.widget !== 'datetime' || field.type === 'date' || raw === undefined) return false;
+  const stored = isoOf(before[field.name]);
+  return stored !== undefined && raw === datetimeInputValue(stored, 'instant');
+};
+
 /** The last value a posted name carried, as text. A repeated name arrives as a list. */
 export const posted = (form: Posted, name: string): string | undefined => {
   if (!Object.hasOwn(form, name)) return undefined;
@@ -79,13 +113,20 @@ function decodeField(field: AdminField, form: Posted): unknown {
 /**
  * Every field the form rendered, decoded. A sealed column rides along as the string that was
  * typed — `crud.ts` drops an empty one, which is what makes an untouched box mean "unchanged".
+ *
+ * `before` is the row an EDIT form was rendered from: an instant that comes back exactly as it was
+ * drawn is left out rather than rewritten at the control's precision. A create has none.
  */
 export function decodeForm(
   resource: AdminResource,
   form: Posted,
+  before?: AdminRow,
 ): Readonly<Record<string, unknown>> {
   const out: Record<string, unknown> = {};
-  for (const field of resource.formFields) out[field.name] = decodeField(field, form);
+  for (const field of resource.formFields) {
+    if (before !== undefined && untouchedInstant(field, posted(form, field.name), before)) continue;
+    out[field.name] = decodeField(field, form);
+  }
   for (const field of resource.secretFields) out[field.name] = posted(form, field.name) ?? '';
   return out;
 }

package/src/form.tsx

@@ -12,6 +12,7 @@ import type { AdminField } from './fields';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
 import { fieldsFor } from './resource-layout';
+import { VERSION_FIELD } from './row-version';
 import type { ValidationIssue } from './validate';
 import type { WidgetContext } from './widget-value';
 import { Widget } from './widgets';
@@ -28,6 +29,11 @@ export interface AdminFormProps<Row extends AdminRow> {
   readonly action: string;
   /** Where Cancel goes — the list for a create, the row for an edit. */
   readonly cancelHref: string;
+  /**
+   * An edit's `rowVersion()` of the row it was rendered from, posted back as `_version` so the
+   * write is refused if the row moved on meanwhile. `null` for a create, which has no row.
+   */
+  readonly version: string | null;
 }
 
 const issuesFor = (issues: readonly ValidationIssue[], field: string): readonly ValidationIssue[] =>
@@ -90,15 +96,23 @@ export function AdminForm<Row extends AdminRow>(props: AdminFormProps<Row>): JSX
   return (
     <Card header={<h2>{t(titleKey, { entity: t(props.resource.titleKey) })}</h2>}>
       <form class={styles['form']} method="post" action={props.action}>
+        {props.version === null ? null : (
+          <input type="hidden" name={VERSION_FIELD} value={props.version} />
+        )}
         {props.issues.length === 0 ? null : (
           <div class="x-admin-issues" role="alert" tabindex={-1}>
             <h3>{t('admin.form.issues')}</h3>
             <ul>
-              {props.issues.map((issue) => (
-                <li>
-                  <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issueText(issue)}
-                </li>
-              ))}
+              {props.issues.map((issue) =>
+                // The form's own issue (the row changed under it) names no control to jump to.
+                issue.path === VERSION_FIELD ? (
+                  <li>{issueText(issue)}</li>
+                ) : (
+                  <li>
+                    <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issueText(issue)}
+                  </li>
+                ),
+              )}
             </ul>
           </div>
         )}

package/src/index.ts

@@ -104,7 +104,6 @@ export {
   type AdminBatchInput,
   type AdminBatchResult,
   BATCH_NOT_OFFERED_REASON,
-  BATCH_QUEUED_REASON,
   type BatchEnqueue,
   type BatchRow,
   type BatchRowOutcome,
@@ -124,7 +123,9 @@ export {
   batchEnqueue,
 } from './batch-job';
 export { BATCH_MATCHING_REASON, matchingConfirmationToken } from './batch-matching';
+export { BATCH_QUEUED_REASON } from './batch-queue';
 export {
+  type AdminUpdateOptions,
   adminCreate,
   adminDestroy,
   adminDetail,
@@ -290,7 +291,6 @@ export {
   ruleFor,
 } from './permissions';
 export {
-  adminPermissions,
   declareAdminPermissions,
   type PolicyAuthzInput,
   policyAuthz,
@@ -382,6 +382,7 @@ export {
   adminRoutes,
 } from './routes';
 export { ROW_OUT_OF_SCOPE_REASON } from './row-scope-write';
+export { ROW_CHANGED_REASON, rowVersion, VERSION_FIELD } from './row-version';
 export {
   type AdminRouteRequest,
   type AdminRouteResponse,