@open-mercato/core 0.6.4-develop.4371.1.8f3030407e → 0.6.4

package/src/helpers/integration/optimisticLockUi.ts

@@ -0,0 +1,172 @@
+import { expect, type APIRequestContext, type Page } from '@playwright/test'
+import {
+  OPTIMISTIC_LOCK_HEADER_NAME,
+  OPTIMISTIC_LOCK_CONFLICT_CODE,
+} from '@open-mercato/shared/lib/crud/optimistic-lock-headers'
+
+/**
+ * Shared helpers for the browser-driven optimistic-lock specs
+ * (`TC-LOCK-OSS-014..046`). They make the conflict deterministic without two
+ * real tabs or sleeps: the spec loads an edit page in the browser (the form
+ * captures the record's `updated_at`), then advances `updated_at` out-of-band
+ * via a header-less API PUT (additive path, always succeeds), and finally edits
+ * + saves in the browser so the now-stale header triggers the 409 → conflict bar.
+ *
+ * See `packages/core/src/modules/sales/__integration__/__concurrent_edit_pattern.md`
+ * and the conflict bar component
+ * `packages/ui/src/backend/conflicts/RecordConflictBanner.tsx`
+ * (`data-testid="record-conflict-banner"`).
+ */
+
+const BASE_URL = process.env.BASE_URL?.trim() || ''
+
+export function resolveApiUrl(path: string): string {
+  return BASE_URL ? `${BASE_URL}${path}` : path
+}
+
+export const CONFLICT_BANNER_TESTID = 'record-conflict-banner'
+
+/**
+ * The enterprise `record_locks` module (enabled in CI via
+ * `OM_ENABLE_ENTERPRISE_MODULES=true`) supersedes the OSS banner with a richer
+ * "Conflict detected" resolution dialog. Both are valid surfaces for "the stale
+ * write was refused": on a CrudForm edit page either one can win depending on
+ * whether the record_locks incoming-changes SSE (fired by the out-of-band bump)
+ * is processed before the browser's stale save reaches the server. Asserting one
+ * fixed surface is therefore racy; we wait for whichever conflict surface appears.
+ * (List-delete / non-form flows have no record_locks lock and only ever surface
+ * the OSS banner, so matching either surface is safe there too.)
+ */
+export const CONFLICT_DIALOG_TESTID = 'record-lock-conflict-dialog'
+
+function authHeaders(token: string, lockValue?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    'Content-Type': 'application/json',
+  }
+  if (lockValue !== undefined) headers[OPTIMISTIC_LOCK_HEADER_NAME] = lockValue
+  return headers
+}
+
+/**
+ * Read a record's current `updated_at` from a list-shaped CRUD GET
+ * (`GET <basePath>?id=<id>` → `items[0].updated_at`), normalized to ISO.
+ * Works for the `makeCrudRoute` list responses (snake or camel case).
+ */
+export async function readUpdatedAt(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  id: string,
+  idParam = 'id',
+): Promise<string> {
+  const response = await request.fetch(
+    resolveApiUrl(`${basePath}?${idParam}=${encodeURIComponent(id)}`),
+    { method: 'GET', headers: authHeaders(token) },
+  )
+  expect(response.status(), `GET ${basePath}?${idParam}=... should be 200`).toBe(200)
+  const body = (await response.json()) as
+    | { items?: Array<Record<string, unknown>> }
+    | Record<string, unknown>
+  const item = Array.isArray((body as { items?: unknown[] }).items)
+    ? (body as { items: Array<Record<string, unknown>> }).items[0]
+    : (body as Record<string, unknown>)
+  expect(item, `response should include the record for id=${id}`).toBeTruthy()
+  const raw = (item?.updated_at ?? item?.updatedAt) as string | undefined
+  expect(typeof raw, `record should expose updated_at, got ${String(raw)}`).toBe('string')
+  const ms = Date.parse(raw as string)
+  expect(Number.isFinite(ms), `updated_at should parse, got ${String(raw)}`).toBe(true)
+  return new Date(ms).toISOString()
+}
+
+/**
+ * Advance a record's `updated_at` out-of-band so the browser's loaded form now
+ * holds a stale token. Uses a **header-less** PUT (the strictly-additive path
+ * always succeeds and bumps `updated_at`). Returns the new ISO `updated_at`.
+ */
+export async function bumpRecordViaApi(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  putBody: Record<string, unknown>,
+  opts: { idParam?: string; method?: 'PUT' | 'PATCH' } = {},
+): Promise<string | null> {
+  const response = await request.fetch(resolveApiUrl(basePath), {
+    method: opts.method ?? 'PUT',
+    headers: authHeaders(token),
+    data: putBody,
+  })
+  expect(
+    response.status(),
+    `out-of-band ${opts.method ?? 'PUT'} ${basePath} should succeed (additive path), got ${response.status()}`,
+  ).toBeLessThan(300)
+  const id = putBody[opts.idParam ?? 'id']
+  if (typeof id === 'string') {
+    try {
+      return await readUpdatedAt(request, token, basePath, id, opts.idParam)
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+/** Direct API helpers to assert the 409 contract body (used by the negative/UX specs). */
+export async function putWithLock(
+  request: APIRequestContext,
+  token: string,
+  basePath: string,
+  body: Record<string, unknown>,
+  lockValue: string,
+) {
+  return request.fetch(resolveApiUrl(basePath), {
+    method: 'PUT',
+    headers: authHeaders(token, lockValue),
+    data: body,
+  })
+}
+
+export async function expectConflictBody(response: { status(): number; json(): Promise<unknown> }) {
+  expect(response.status(), 'stale write should be 409').toBe(409)
+  const body = (await response.json()) as { code?: string; currentUpdatedAt?: string; expectedUpdatedAt?: string }
+  expect(body.code, 'body.code should be the optimistic-lock conflict code').toBe(OPTIMISTIC_LOCK_CONFLICT_CODE)
+  return body
+}
+
+/**
+ * Assert a stale save was refused and surfaced as a conflict. Matches EITHER the
+ * OSS `record-conflict-banner` OR the enterprise record_locks "Conflict detected"
+ * dialog — see `CONFLICT_DIALOG_TESTID` for why both are valid and why pinning one
+ * is racy when enterprise modules are enabled.
+ */
+export async function expectConflictBanner(page: Page): Promise<void> {
+  const conflictSurface = page
+    .getByTestId(CONFLICT_BANNER_TESTID)
+    .or(page.getByTestId(CONFLICT_DIALOG_TESTID))
+  await expect(
+    conflictSurface.first(),
+    'a conflict surface (OSS bar or record_locks dialog) should appear after a stale save',
+  ).toBeVisible({ timeout: 10_000 })
+}
+
+/** Assert no conflict surface is present (a clean single-tab save must not 409). */
+export async function expectNoConflictBanner(page: Page): Promise<void> {
+  await expect(
+    page.getByTestId(CONFLICT_BANNER_TESTID),
+    'a clean save must not surface a false-positive conflict bar',
+  ).toHaveCount(0)
+  await expect(
+    page.getByTestId(CONFLICT_DIALOG_TESTID),
+    'a clean save must not surface a false-positive conflict dialog',
+  ).toHaveCount(0)
+}
+
+/** Click the conflict bar's Refresh button. */
+export async function clickConflictRefresh(page: Page): Promise<void> {
+  await page.getByTestId(CONFLICT_BANNER_TESTID).getByRole('button', { name: /refresh/i }).click()
+}
+
+/** Dismiss the conflict bar via its close (X) button. */
+export async function dismissConflictBanner(page: Page): Promise<void> {
+  await page.getByTestId(CONFLICT_BANNER_TESTID).getByRole('button', { name: /dismiss/i }).click()
+}

package/src/helpers/integration/salesFixtures.ts

@@ -73,6 +73,35 @@ export async function createOrderLineFixture(
   );
 }
 
+/**
+ * Probe whether the authenticated principal can create a sales order on the
+ * current tenant (i.e. holds `sales.orders.manage`). Sales-write integration
+ * specs use this to self-skip on dev databases whose role ACLs were never
+ * synced (`yarn mercato auth sync-role-acls`) rather than fail spuriously —
+ * CI bootstraps a fully-synced tenant so the probe passes there. The probed
+ * order is deleted immediately so the check leaves no residue.
+ */
+export async function canManageSalesOrders(
+  request: APIRequestContext,
+  token: string,
+): Promise<boolean> {
+  const response = await apiRequest(request, 'POST', '/api/sales/orders', {
+    token,
+    data: { currencyCode: 'USD' },
+  });
+  if (response.status() === 403) return false;
+  if (!response.ok()) return false;
+  const id = readId((await response.json()) as unknown, ['id', 'orderId']);
+  if (id) {
+    try {
+      await apiRequest(request, 'DELETE', '/api/sales/orders', { token, data: { id } });
+    } catch {
+      // best-effort cleanup
+    }
+  }
+  return true;
+}
+
 export async function deleteSalesEntityIfExists(
   request: APIRequestContext,
   token: string | null,

package/src/helpers/integration/salesUi.ts

@@ -78,7 +78,7 @@ type AddAdjustmentOptions = {
   netAmount: number;
 };
 
-const TEST_WAIT_TIMEOUT_MS = 10_000;
+const TEST_WAIT_TIMEOUT_MS = 15_000;
 
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -522,15 +522,21 @@ async function resolveSalesChannelId(page: Page, token: string, channelQuery: st
 }
 
 async function resolveOrderLineId(page: Page, token: string, orderId: string): Promise<string | null> {
-  const response = await apiRequest(page.request, 'GET', `/api/sales/order-lines?page=1&pageSize=20&orderId=${orderId}`, {
-    token,
-  }).catch(() => null);
-  const body = (await response?.json().catch(() => null)) as {
-    result?: { items?: SalesOrderLineListItem[] };
-    items?: SalesOrderLineListItem[];
-  } | null;
-  const items = readListItems(body);
-  return items.find((item) => typeof item.id === 'string' && item.id.length > 0)?.id ?? null;
+  const deadline = Date.now() + TEST_WAIT_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const response = await apiRequest(page.request, 'GET', `/api/sales/order-lines?page=1&pageSize=20&orderId=${orderId}`, {
+      token,
+    }).catch(() => null);
+    const body = (await response?.json().catch(() => null)) as {
+      result?: { items?: SalesOrderLineListItem[] };
+      items?: SalesOrderLineListItem[];
+    } | null;
+    const items = readListItems(body);
+    const lineId = items.find((item) => typeof item.id === 'string' && item.id.length > 0)?.id ?? null;
+    if (lineId) return lineId;
+    await page.waitForTimeout(250).catch(() => {});
+  }
+  return null;
 }
 
 async function resolveShippingMethodId(page: Page, token: string): Promise<string | null> {
@@ -1296,7 +1302,7 @@ export async function addShipment(page: Page): Promise<{ trackingNumber: string;
     await dialog
       .getByText(/Loading shipments…|Loading shipments\.\.\./i)
       .first()
-      .waitFor({ state: 'hidden', timeout: 5_000 })
+      .waitFor({ state: 'hidden', timeout: TEST_WAIT_TIMEOUT_MS })
       .catch(() => {});
     const shipmentNumberInput = dialog.locator('input, textarea').first();
     if (await shipmentNumberInput.isVisible().catch(() => false)) {
@@ -1371,7 +1377,8 @@ export async function addShipment(page: Page): Promise<{ trackingNumber: string;
   }
 
   if (!closed) {
-    return { trackingNumber, shipmentNumber, added: false };
+    const added = await addShipmentViaApi(page, shipmentNumber, trackingNumber);
+    return { trackingNumber, shipmentNumber, added };
   }
 
   await page.getByRole('button', { name: /^Shipments$/i }).click();

package/src/helpers/integration/standaloneEnv.ts

@@ -0,0 +1,62 @@
+import fs from 'fs';
+import path from 'path';
+
+const truthyValues = new Set(['1', 'true', 'yes', 'on']);
+const falsyValues = new Set(['0', 'false', 'no', 'off']);
+
+let cachedStandaloneEnv: Record<string, string> | null = null;
+
+function parseDotEnv(contents: string): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const line of contents.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const index = trimmed.indexOf('=');
+    if (index <= 0) continue;
+    const key = trimmed.slice(0, index).trim();
+    let value = trimmed.slice(index + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[key] = value;
+  }
+  return values;
+}
+
+export function readStandaloneEnv(): Record<string, string> {
+  if (cachedStandaloneEnv) return cachedStandaloneEnv;
+  const appRoot = process.env.OM_TEST_APP_ROOT?.trim();
+  if (!appRoot) {
+    cachedStandaloneEnv = {};
+    return cachedStandaloneEnv;
+  }
+
+  const envPath = path.join(appRoot, '.env');
+  try {
+    cachedStandaloneEnv = parseDotEnv(fs.readFileSync(envPath, 'utf8'));
+  } catch {
+    cachedStandaloneEnv = {};
+  }
+  return cachedStandaloneEnv;
+}
+
+export function readIntegrationEnv(name: string): string | undefined {
+  const fromProcess = process.env[name];
+  if (typeof fromProcess === 'string') return fromProcess;
+  return readStandaloneEnv()[name];
+}
+
+export function isStandaloneIntegration(): boolean {
+  return Boolean(process.env.OM_TEST_APP_ROOT?.trim());
+}
+
+export function readIntegrationEnvFlag(name: string, defaultValue = false): boolean {
+  const raw = readIntegrationEnv(name)?.trim().toLowerCase();
+  if (!raw) return defaultValue;
+  if (truthyValues.has(raw)) return true;
+  if (falsyValues.has(raw)) return false;
+  return defaultValue;
+}

package/src/helpers/integration/undoHarness.ts

@@ -0,0 +1,243 @@
+import { type APIRequestContext, type APIResponse, expect, test } from '@playwright/test'
+import { randomInt } from 'node:crypto'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { apiRequest } from './api'
+import { expectId, readJsonSafe } from './generalFixtures'
+
+/**
+ * Shared harness for verifying Undo/Redo correctness against the real command bus.
+ *
+ * Every mutating Open Mercato API response carries the operation metadata in the
+ * `x-om-operation` header (`omop:<urlencoded JSON>`) containing the `undoToken` and the
+ * audit log `id` (used as `logId` for redo). These helpers extract that envelope and drive
+ * the real undo/redo endpoints so tests can assert full state restoration per TC-UNDO-001.
+ */
+
+const HEADER_PREFIX = 'omop:'
+const UNDO_PATH = '/api/audit_logs/audit-logs/actions/undo'
+const REDO_PATH = '/api/audit_logs/audit-logs/actions/redo'
+const ACTIONS_PATH = '/api/audit_logs/audit-logs/actions'
+export const UNDO_TESTS_DISABLED_ENV = 'OM_INTEGRATION_UNDO_TESTS_DISABLED'
+
+export type Operation = {
+  logId: string
+  undoToken: string
+  commandId: string
+  resourceKind: string | null
+  resourceId: string | null
+}
+
+export type CrudUndoEntityConfig = {
+  label: string
+  collectionPath: string
+  field: string
+  createPayload: (stamp: string) => Record<string, unknown>
+  updatePayload: (id: string, stamp: string) => Record<string, unknown>
+  readPath?: (id: string) => string
+  deletePath?: (id: string) => string
+  createStatus?: number
+  updateStatus?: number
+}
+
+export function undoTestsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return parseBooleanWithDefault(env[UNDO_TESTS_DISABLED_ENV], false)
+}
+
+export function skipIfUndoTestsDisabled(): void {
+  test.skip(undoTestsDisabled(), `${UNDO_TESTS_DISABLED_ENV} is set — undo/redo integration tests skipped`)
+}
+
+/** Parse the `x-om-operation` header into a structured operation, or null when absent/malformed. */
+export function extractOperation(response: APIResponse): Operation | null {
+  const header = response.headers()['x-om-operation']
+  if (!header || typeof header !== 'string') return null
+  const trimmed = header.startsWith(HEADER_PREFIX) ? header.slice(HEADER_PREFIX.length) : header
+  try {
+    const parsed = JSON.parse(decodeURIComponent(trimmed)) as Record<string, unknown>
+    if (typeof parsed.id !== 'string' || typeof parsed.commandId !== 'string') return null
+    if (typeof parsed.undoToken !== 'string' || !parsed.undoToken) return null
+    return {
+      logId: parsed.id,
+      undoToken: parsed.undoToken,
+      commandId: parsed.commandId,
+      resourceKind: (parsed.resourceKind as string) ?? null,
+      resourceId: (parsed.resourceId as string) ?? null,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Like extractOperation but fails the test if no undo token was issued. */
+export function expectOperation(response: APIResponse, context: string): Operation {
+  const op = extractOperation(response)
+  expect(op, `Expected an undo token (x-om-operation header) for ${context}, got none`).toBeTruthy()
+  return op as Operation
+}
+
+export async function undoByToken(request: APIRequestContext, token: string, undoToken: string): Promise<APIResponse> {
+  return apiRequest(request, 'POST', UNDO_PATH, { token, data: { undoToken } })
+}
+
+export async function redoByLogId(request: APIRequestContext, token: string, logId: string): Promise<APIResponse> {
+  return apiRequest(request, 'POST', REDO_PATH, { token, data: { logId } })
+}
+
+/** Undo and assert success; returns the resolved logId. */
+export async function undoOk(request: APIRequestContext, token: string, undoToken: string, context: string): Promise<string> {
+  const res = await undoByToken(request, token, undoToken)
+  const body = (await res.json().catch(() => null)) as { ok?: boolean; logId?: string } | null
+  expect(res.ok(), `Undo failed for ${context}: status ${res.status()} body ${JSON.stringify(body)}`).toBeTruthy()
+  expect(body?.ok, `Undo not ok for ${context}: ${JSON.stringify(body)}`).toBeTruthy()
+  return body?.logId as string
+}
+
+/** Redo and assert success; returns the new operation (new undoToken + logId). */
+export async function redoOk(request: APIRequestContext, token: string, logId: string, context: string): Promise<{ logId: string; undoToken: string | null }> {
+  const res = await redoByLogId(request, token, logId)
+  const body = (await res.json().catch(() => null)) as { ok?: boolean; logId?: string; undoToken?: string } | null
+  expect(res.ok(), `Redo failed for ${context}: status ${res.status()} body ${JSON.stringify(body)}`).toBeTruthy()
+  expect(body?.ok, `Redo not ok for ${context}: ${JSON.stringify(body)}`).toBeTruthy()
+  return { logId: body?.logId as string, undoToken: body?.undoToken ?? null }
+}
+
+/** Assert that undoing an already-consumed token is rejected (token consumption / no double-undo). */
+export async function expectTokenConsumed(request: APIRequestContext, token: string, undoToken: string, context: string): Promise<void> {
+  const res = await undoByToken(request, token, undoToken)
+  expect(res.ok(), `Expected double-undo to be rejected for ${context}, but it succeeded`).toBeFalsy()
+}
+
+/** Fetch undoable actions list (for Version History assertions). */
+export async function listUndoable(request: APIRequestContext, token: string, params: Record<string, string> = {}): Promise<unknown> {
+  const qs = new URLSearchParams({ undoableOnly: 'true', ...params }).toString()
+  const res = await apiRequest(request, 'GET', `${ACTIONS_PATH}?${qs}`, { token })
+  return res.json().catch(() => null)
+}
+
+/**
+ * Deep-equality assertion for a selected set of fields between two entity snapshots.
+ * Reports the first mismatching field with context for clear bug triage.
+ */
+export function assertFieldsEqual(
+  actual: Record<string, unknown> | null | undefined,
+  expected: Record<string, unknown> | null | undefined,
+  fields: string[],
+  context: string,
+): void {
+  expect(actual, `${context}: actual entity missing`).toBeTruthy()
+  expect(expected, `${context}: expected entity missing`).toBeTruthy()
+  for (const field of fields) {
+    expect(
+      JSON.stringify((actual as Record<string, unknown>)[field]),
+      `${context}: field "${field}" not restored (expected ${JSON.stringify((expected as Record<string, unknown>)[field])}, got ${JSON.stringify((actual as Record<string, unknown>)[field])})`,
+    ).toBe(JSON.stringify((expected as Record<string, unknown>)[field]))
+  }
+}
+
+function findRecord(body: unknown, id: string): Record<string, unknown> | null {
+  if (!body || typeof body !== 'object') return null
+  if (!Array.isArray(body) && (body as Record<string, unknown>).id === id) {
+    return body as Record<string, unknown>
+  }
+  for (const value of Array.isArray(body) ? body : Object.values(body)) {
+    const found = findRecord(value, id)
+    if (found) return found
+  }
+  return null
+}
+
+async function readRecord(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+  id: string,
+): Promise<Record<string, unknown> | null> {
+  const path = entity.readPath?.(id) ?? `${entity.collectionPath}?id=${encodeURIComponent(id)}`
+  const response = await apiRequest(request, 'GET', path, { token })
+  const body = await readJsonSafe(response)
+  if (!response.ok()) return null
+  return findRecord(body, id)
+}
+
+function fieldValue(record: Record<string, unknown> | null, field: string): unknown {
+  return record?.[field]
+}
+
+async function deleteEntity(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+  id: string,
+): Promise<APIResponse> {
+  const path = entity.deletePath?.(id) ?? `${entity.collectionPath}?id=${encodeURIComponent(id)}`
+  return apiRequest(request, 'DELETE', path, { token })
+}
+
+export async function runCrudUndoRoundTrip(
+  request: APIRequestContext,
+  token: string,
+  entity: CrudUndoEntityConfig,
+): Promise<void> {
+  const stamp = `${Date.now()}${randomInt(1000)}`
+  let createUndoId: string | null = null
+  let cycleId: string | null = null
+
+  try {
+    const createUndoRes = await apiRequest(request, 'POST', entity.collectionPath, {
+      token,
+      data: entity.createPayload(`${stamp}a`),
+    })
+    expect(createUndoRes.status(), `${entity.label} create-for-undo status`).toBe(entity.createStatus ?? 201)
+    const createUndoOp = expectOperation(createUndoRes, `${entity.label}.create`)
+    createUndoId = createUndoOp.resourceId || expectId((await readJsonSafe<Record<string, unknown>>(createUndoRes))?.id, `${entity.label} create id`)
+    expect(fieldValue(await readRecord(request, token, entity, createUndoId), entity.field), `${entity.label} field readable after create`).toBeDefined()
+
+    await undoOk(request, token, createUndoOp.undoToken, `${entity.label} undo create`)
+    expect(await readRecord(request, token, entity, createUndoId), `${entity.label} create→undo soft-deletes/removes the record (I3)`).toBeNull()
+    await expectTokenConsumed(request, token, createUndoOp.undoToken, `${entity.label} create token consumed (I5)`)
+
+    const createRes = await apiRequest(request, 'POST', entity.collectionPath, {
+      token,
+      data: entity.createPayload(`${stamp}b`),
+    })
+    expect(createRes.status(), `${entity.label} create status`).toBe(entity.createStatus ?? 201)
+    const createOp = expectOperation(createRes, `${entity.label}.create`)
+    cycleId = createOp.resourceId || expectId((await readJsonSafe<Record<string, unknown>>(createRes))?.id, `${entity.label} cycle id`)
+
+    const beforeUpdate = await readRecord(request, token, entity, cycleId)
+    const beforeValue = fieldValue(beforeUpdate, entity.field)
+    expect(beforeValue, `${entity.label} field readable before update`).toBeDefined()
+
+    const updateRes = await apiRequest(request, 'PUT', entity.collectionPath, {
+      token,
+      data: entity.updatePayload(cycleId, stamp),
+    })
+    expect(updateRes.status(), `${entity.label} update status`).toBe(entity.updateStatus ?? 200)
+    const updateOp = expectOperation(updateRes, `${entity.label}.update`)
+    const afterUpdate = await readRecord(request, token, entity, cycleId)
+    const afterUpdateValue = fieldValue(afterUpdate, entity.field)
+    expect(JSON.stringify(afterUpdateValue), `${entity.label} field changed by update`).not.toBe(JSON.stringify(beforeValue))
+
+    await new Promise((resolve) => setTimeout(resolve, 10))
+    await undoOk(request, token, updateOp.undoToken, `${entity.label} undo update`)
+    const afterUndo = await readRecord(request, token, entity, cycleId)
+    expect(JSON.stringify(fieldValue(afterUndo, entity.field)), `${entity.label} update→undo restores ${entity.field} (I1)`).toBe(JSON.stringify(beforeValue))
+    if (typeof beforeUpdate?.updatedAt === 'string' && typeof afterUndo?.updatedAt === 'string') {
+      expect(afterUndo.updatedAt, `${entity.label} undo bumps updatedAt`).not.toBe(beforeUpdate.updatedAt)
+    }
+
+    await redoOk(request, token, updateOp.logId, `${entity.label} redo update`)
+    expect(JSON.stringify(fieldValue(await readRecord(request, token, entity, cycleId), entity.field)), `${entity.label} redo re-applies update (I6)`).toBe(JSON.stringify(afterUpdateValue))
+
+    const deleteRes = await deleteEntity(request, token, entity, cycleId)
+    expect(deleteRes.ok(), `${entity.label} delete status ${deleteRes.status()}`).toBeTruthy()
+    const deleteOp = expectOperation(deleteRes, `${entity.label}.delete`)
+    expect(await readRecord(request, token, entity, cycleId), `${entity.label} deleted record should not read`).toBeNull()
+
+    await undoOk(request, token, deleteOp.undoToken, `${entity.label} undo delete`)
+    expect(fieldValue(await readRecord(request, token, entity, cycleId), entity.field), `${entity.label} delete→undo re-materializes (I2)`).toBeDefined()
+  } finally {
+    if (createUndoId) await deleteEntity(request, token, entity, createUndoId).catch(() => {})
+    if (cycleId) await deleteEntity(request, token, entity, cycleId).catch(() => {})
+  }
+}