@open-mercato/shared 0.6.5-canary.4425.1.75a266b232 → 0.6.5-develop.4393.1.de282b5dfd

package/dist/lib/crud/optimistic-lock.js

@@ -1,172 +0,0 @@
-import {
-  OPTIMISTIC_LOCK_CONFLICT_CODE,
-  OPTIMISTIC_LOCK_CONFLICT_ERROR,
-  OPTIMISTIC_LOCK_ENV_VAR,
-  OPTIMISTIC_LOCK_HEADER_NAME
-} from "./optimistic-lock-headers.js";
-import { getAllOptimisticLockReaders } from "./optimistic-lock-store.js";
-const OPTIMISTIC_LOCK_OFF_TOKENS = /* @__PURE__ */ new Set([
-  "off",
-  "false",
-  "0",
-  "no",
-  "disabled",
-  "none"
-]);
-function parseOptimisticLockEnv(raw) {
-  if (raw == null) return { mode: "all" };
-  const trimmed = String(raw).trim();
-  if (trimmed === "") return { mode: "all" };
-  const tokens = trimmed.split(",").map((token) => token.trim().toLowerCase()).filter((token) => token.length > 0);
-  if (tokens.length === 0) return { mode: "all" };
-  if (tokens.some((token) => OPTIMISTIC_LOCK_OFF_TOKENS.has(token))) return { mode: "off" };
-  if (tokens.includes("all")) return { mode: "all" };
-  return { mode: "allowlist", entities: new Set(tokens) };
-}
-const defaultResolveExpectedUpdatedAt = ({ expectedFromHeader }) => expectedFromHeader;
-function createGenericOptimisticLockReader(opts) {
-  const idField = opts.idField ?? "id";
-  const tenantField = opts.tenantField === null ? null : opts.tenantField ?? "tenantId";
-  const orgField = opts.orgField === null ? null : opts.orgField ?? "organizationId";
-  const softDeleteField = opts.softDeleteField === null ? null : opts.softDeleteField ?? "deletedAt";
-  const updatedAtField = opts.updatedAtField ?? "updatedAt";
-  const extraFilter = opts.extraFilter ?? {};
-  return async (em, { resourceId, tenantId, organizationId }) => {
-    const filter = { [idField]: resourceId };
-    if (tenantField) filter[tenantField] = tenantId;
-    if (orgField && organizationId) filter[orgField] = organizationId;
-    if (softDeleteField) filter[softDeleteField] = null;
-    for (const [key, value] of Object.entries(extraFilter)) filter[key] = value;
-    try {
-      const row = await em.findOne(opts.entity, filter, {
-        fields: [updatedAtField]
-      });
-      if (!row || typeof row !== "object") return null;
-      const value = row[updatedAtField];
-      if (value instanceof Date) return value.toISOString();
-      if (typeof value === "string" && value.length > 0) return value;
-      return null;
-    } catch {
-      return null;
-    }
-  };
-}
-function readHeader(headers, name) {
-  const direct = headers.get(name);
-  if (typeof direct === "string" && direct.trim().length > 0) return direct.trim();
-  return null;
-}
-function normalizeIsoToken(raw) {
-  const ms = Date.parse(raw);
-  if (!Number.isFinite(ms)) return null;
-  return new Date(ms).toISOString();
-}
-function buildConflictBody(currentIso, expectedIso) {
-  return {
-    error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
-    code: OPTIMISTIC_LOCK_CONFLICT_CODE,
-    currentUpdatedAt: currentIso,
-    expectedUpdatedAt: expectedIso
-  };
-}
-function createOptimisticLockGuardService(opts) {
-  const envValue = opts.envValue !== void 0 ? opts.envValue : process.env[OPTIMISTIC_LOCK_ENV_VAR];
-  const config = parseOptimisticLockEnv(envValue);
-  const resolveExpected = opts.resolveExpected ?? defaultResolveExpectedUpdatedAt;
-  const debugEnabled = process.env.OM_OPTIMISTIC_LOCK_DEBUG === "1";
-  function isEntityEnabled(resourceKind) {
-    if (config.mode === "off") return false;
-    if (config.mode === "all") return true;
-    return config.entities.has(resourceKind.toLowerCase());
-  }
-  async function validateMutation(input) {
-    if (config.mode === "off") {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    if (input.operation !== "update" && input.operation !== "delete") {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    if (!isEntityEnabled(input.resourceKind)) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    const readers = opts.readers ?? getAllOptimisticLockReaders();
-    const reader = readers[input.resourceKind];
-    if (!reader) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    const expectedRaw = readHeader(input.requestHeaders, OPTIMISTIC_LOCK_HEADER_NAME);
-    const resolvedExpected = await resolveExpected({
-      expectedFromHeader: expectedRaw,
-      resourceKind: input.resourceKind,
-      resourceId: input.resourceId
-    });
-    if (resolvedExpected == null) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    const expectedIso = normalizeIsoToken(resolvedExpected);
-    if (expectedIso == null) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    const em = opts.getEm();
-    const currentRaw = await reader(em, {
-      resourceKind: input.resourceKind,
-      resourceId: input.resourceId,
-      tenantId: input.tenantId,
-      organizationId: input.organizationId ?? null
-    });
-    if (currentRaw == null) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    const currentIso = normalizeIsoToken(currentRaw);
-    if (currentIso == null) {
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    if (currentIso === expectedIso) {
-      if (debugEnabled) {
-        console.log("[optimistic-lock] match", {
-          resourceKind: input.resourceKind,
-          resourceId: input.resourceId,
-          operation: input.operation,
-          currentIso,
-          expectedIso
-        });
-      }
-      return { ok: true, shouldRunAfterSuccess: false };
-    }
-    if (debugEnabled) {
-      console.log("[optimistic-lock] CONFLICT", {
-        resourceKind: input.resourceKind,
-        resourceId: input.resourceId,
-        operation: input.operation,
-        tenantId: input.tenantId,
-        organizationId: input.organizationId ?? null,
-        expectedRaw: resolvedExpected,
-        expectedIso,
-        currentRaw,
-        currentIso
-      });
-    }
-    return {
-      ok: false,
-      status: 409,
-      body: buildConflictBody(currentIso, expectedIso)
-    };
-  }
-  async function afterMutationSuccess(_input) {
-  }
-  function getConfig() {
-    return config;
-  }
-  return {
-    validateMutation,
-    afterMutationSuccess,
-    getConfig
-  };
-}
-export {
-  createGenericOptimisticLockReader,
-  createOptimisticLockGuardService,
-  normalizeIsoToken,
-  parseOptimisticLockEnv
-};
-//# sourceMappingURL=optimistic-lock.js.map

package/dist/lib/crud/optimistic-lock.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/lib/crud/optimistic-lock.ts"],
-  "sourcesContent": ["/**\n * OSS optimistic-locking guard service.\n *\n * Registered as `crudMutationGuardService` (by the platform DI bootstrap and\n * by hand-wiring modules that override the default reader). Compares the\n * client-sent expected `updated_at` (carried via the extension header\n * defined in `optimistic-lock-headers.ts`) against the current DB\n * `updated_at` for the target entity; on mismatch returns HTTP 409 with the\n * structured `OptimisticLockConflictBody`.\n *\n * **Default ON** (Phase 14, 2026-05-27). Activate / scope / disable via\n * `OM_OPTIMISTIC_LOCK`:\n *   - unset / empty / whitespace    \u2192 ON for every CRUD entity (`{ mode: 'all' }`)\n *   - `all`                         \u2192 all entities (explicit form of the default)\n *   - `customers.company,sales.order` \u2192 allow-list (lowercased, trimmed, deduped)\n *   - `off` / `false` / `0` / `no` / `disabled` / `none` \u2192 fully disabled\n *\n * The guard is still strictly additive at runtime: clients that do not send\n * the `x-om-ext-optimistic-lock-expected-updated-at` header pass through\n * unchanged, so flipping the default to ON cannot introduce new 409s on\n * existing API consumers. Pages that opt into the round-trip (via\n * `CrudForm`'s `optimisticLockUpdatedAt` prop or by calling\n * `buildOptimisticLockHeader`) gain protection without any per-deployment\n * env change.\n *\n * Cannot be registered as a static `data/guards.ts` `MutationGuard` because\n * the static `validate(input)` receives only `MutationGuardInput` \u2014 no\n * container / em access. Stateful checks that need to read current DB state\n * MUST go through the DI service path (this file).\n *\n * Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md\n */\nimport type { EntityManager } from '@mikro-orm/postgresql'\nimport type {\n  CrudMutationGuardValidateInput,\n  CrudMutationGuardValidationResult,\n  CrudMutationGuardAfterSuccessInput,\n} from './mutation-guard'\nimport {\n  OPTIMISTIC_LOCK_CONFLICT_CODE,\n  OPTIMISTIC_LOCK_CONFLICT_ERROR,\n  OPTIMISTIC_LOCK_ENV_VAR,\n  OPTIMISTIC_LOCK_HEADER_NAME,\n  type OptimisticLockConflictBody,\n} from './optimistic-lock-headers'\nimport { getAllOptimisticLockReaders } from './optimistic-lock-store'\n\nexport type OptimisticLockConfig =\n  | { mode: 'off' }\n  | { mode: 'all' }\n  | { mode: 'allowlist'; entities: ReadonlySet<string> }\n\n/**\n * Tokens (case-insensitive, single-token-only) that explicitly disable the\n * guard. Spelled out as a fixed set so tests can pin them; deliberately the\n * same shape `parseBooleanToken` recognises so operators can mirror existing\n * habit. Mixing an off-token with other entities is invalid input \u2014 we treat\n * any presence of an off-token in the comma list as a request to disable.\n */\nconst OPTIMISTIC_LOCK_OFF_TOKENS: ReadonlySet<string> = new Set([\n  'off',\n  'false',\n  '0',\n  'no',\n  'disabled',\n  'none',\n])\n\n/**\n * Pure parser for `OM_OPTIMISTIC_LOCK`. Exported separately so tests can\n * exercise the grammar without spinning up the full service.\n *\n * Default is **ON** (`{ mode: 'all' }`) \u2014 unset / empty / whitespace input\n * activates the guard for every CRUD entity. Operators opt out via\n * `OM_OPTIMISTIC_LOCK=off` (or `false` / `0` / `no` / `disabled` / `none`).\n */\nexport function parseOptimisticLockEnv(raw: string | undefined | null): OptimisticLockConfig {\n  if (raw == null) return { mode: 'all' }\n  const trimmed = String(raw).trim()\n  if (trimmed === '') return { mode: 'all' }\n\n  const tokens = trimmed\n    .split(',')\n    .map((token) => token.trim().toLowerCase())\n    .filter((token) => token.length > 0)\n\n  if (tokens.length === 0) return { mode: 'all' }\n  if (tokens.some((token) => OPTIMISTIC_LOCK_OFF_TOKENS.has(token))) return { mode: 'off' }\n  if (tokens.includes('all')) return { mode: 'all' }\n\n  return { mode: 'allowlist', entities: new Set(tokens) }\n}\n\nexport type OptimisticLockResolverInput = {\n  expectedFromHeader: string | null\n  resourceKind: string\n  resourceId: string\n}\n\n/**\n * Hook reserved for the enterprise `record_locks` module to override token\n * resolution (e.g. read the expected token from a lock record instead of\n * the request header). OSS keeps the default = \"what the client sent\".\n *\n * Documented as part of the enterprise extension contract; not used in OSS\n * itself.\n */\nexport type ResolveExpectedUpdatedAt = (\n  input: OptimisticLockResolverInput,\n) => Promise<string | null> | string | null\n\nconst defaultResolveExpectedUpdatedAt: ResolveExpectedUpdatedAt = ({ expectedFromHeader }) =>\n  expectedFromHeader\n\nexport type OptimisticLockCurrentReader = (\n  em: EntityManager,\n  input: { resourceKind: string; resourceId: string; tenantId: string; organizationId: string | null },\n) => Promise<string | null>\n\nexport type GenericOptimisticLockReaderOptions = {\n  /** MikroORM entity class. */\n  entity: unknown\n  /** Primary key field. Defaults to `id`. */\n  idField?: string\n  /** Tenant scope field. Defaults to `tenantId`. Pass `null` to skip tenant scoping (rare \u2014 only when the entity itself has no `tenantId` column). */\n  tenantField?: string | null\n  /** Organization scope field. Defaults to `organizationId`. Pass `null` to skip organization scoping. */\n  orgField?: string | null\n  /** Soft-delete column. Defaults to `deletedAt`. Pass `null` to skip the implicit not-deleted filter. */\n  softDeleteField?: string | null\n  /** Optional fixed filter merged into every query (e.g. `{ kind: 'company' }` for a discriminated table). */\n  extraFilter?: Record<string, unknown>\n  /** Optional ORM field name carrying the timestamp. Defaults to `updatedAt`. */\n  updatedAtField?: string\n}\n\n/**\n * Build a generic optimistic-lock reader for any ORM entity that follows the\n * platform conventions (`id` + `tenantId` + `organizationId` + `deletedAt` +\n * `updatedAt`). The reader projects only the timestamp column so PII never\n * materializes.\n *\n * Used by `makeCrudRoute` to auto-register one reader per CRUD route at\n * module-load time (see Phase 13 of the OSS optimistic-locking spec).\n * Module authors who need bespoke filtering (e.g. discriminator on a shared\n * table) keep registering their own reader via `registerOptimisticLockReaders`\n * \u2014 those hand-wired registrations win because they land first.\n *\n * Fail-open contract: if the underlying `findOne` throws (missing column,\n * schema drift, mid-migration) the reader returns `null`, which the guard\n * treats as \"entity already gone\" and lets the CRUD path's own 404 fire.\n * We MUST NOT throw out of the reader \u2014 that would 500 every mutation on\n * the affected entity instead of opting it out of the optimistic check.\n */\nexport function createGenericOptimisticLockReader(\n  opts: GenericOptimisticLockReaderOptions,\n): OptimisticLockCurrentReader {\n  const idField = opts.idField ?? 'id'\n  const tenantField = opts.tenantField === null ? null : opts.tenantField ?? 'tenantId'\n  const orgField = opts.orgField === null ? null : opts.orgField ?? 'organizationId'\n  const softDeleteField = opts.softDeleteField === null ? null : opts.softDeleteField ?? 'deletedAt'\n  const updatedAtField = opts.updatedAtField ?? 'updatedAt'\n  const extraFilter = opts.extraFilter ?? {}\n\n  return async (em, { resourceId, tenantId, organizationId }) => {\n    const filter: Record<string, unknown> = { [idField]: resourceId }\n    if (tenantField) filter[tenantField] = tenantId\n    if (orgField && organizationId) filter[orgField] = organizationId\n    if (softDeleteField) filter[softDeleteField] = null\n    for (const [key, value] of Object.entries(extraFilter)) filter[key] = value\n\n    try {\n      const row = await em.findOne(opts.entity as never, filter as never, {\n        fields: [updatedAtField] as never,\n      })\n      if (!row || typeof row !== 'object') return null\n      const value = (row as Record<string, unknown>)[updatedAtField]\n      if (value instanceof Date) return value.toISOString()\n      if (typeof value === 'string' && value.length > 0) return value\n      return null\n    } catch {\n      return null\n    }\n  }\n}\n\nexport type OptimisticLockGuardOptions = {\n  /** EntityManager resolver. Container-bound via DI in real usage. */\n  getEm: () => EntityManager\n  /**\n   * Maps `resourceKind` \u2192 reader that returns the current\n   * `updated_at` as an ISO string (or null when not found).\n   *\n   * The reader receives the EM so module authors can choose the\n   * right `findOne` shape for their entity (`findOneWithDecryption`\n   * when sensitive, plain `findOne` otherwise \u2014 but only requesting\n   * `updated_at` so no PII materializes).\n   *\n   * When omitted, the service pulls readers from the shared\n   * `optimistic-lock-store` (the recommended pattern for multi-module\n   * deployments \u2014 each module registers its own readers via\n   * `registerOptimisticLockReaders(...)` at module-load time).\n   */\n  readers?: Record<string, OptimisticLockCurrentReader>\n  /** Override env source (mostly for tests). Defaults to `process.env`. */\n  envValue?: string | null\n  /** Override the token resolver. Defaults to \"use the header value\". */\n  resolveExpected?: ResolveExpectedUpdatedAt\n}\n\nexport type OptimisticLockGuardService = {\n  validateMutation: (input: CrudMutationGuardValidateInput) => Promise<CrudMutationGuardValidationResult>\n  afterMutationSuccess: (input: CrudMutationGuardAfterSuccessInput) => Promise<void>\n  /** Exposed for tests / introspection. */\n  getConfig: () => OptimisticLockConfig\n}\n\nfunction readHeader(headers: Headers, name: string): string | null {\n  const direct = headers.get(name)\n  if (typeof direct === 'string' && direct.trim().length > 0) return direct.trim()\n  return null\n}\n\n/**\n * Normalize an `updated_at` token to a canonical ISO-8601 string, or `null`\n * when the input cannot be parsed. Exported so the command-level helper\n * (`optimistic-lock-command.ts`) compares timestamps with the EXACT same\n * normalization as the CRUD guard \u2014 otherwise the same instant could compare\n * unequal across the two paths.\n */\nexport function normalizeIsoToken(raw: string): string | null {\n  const ms = Date.parse(raw)\n  if (!Number.isFinite(ms)) return null\n  return new Date(ms).toISOString()\n}\n\nfunction buildConflictBody(currentIso: string, expectedIso: string): OptimisticLockConflictBody {\n  return {\n    error: OPTIMISTIC_LOCK_CONFLICT_ERROR,\n    code: OPTIMISTIC_LOCK_CONFLICT_CODE,\n    currentUpdatedAt: currentIso,\n    expectedUpdatedAt: expectedIso,\n  }\n}\n\n/**\n * Factory for the optimistic-lock guard service.\n *\n * Usage from a module's `di.ts`:\n *\n * ```ts\n * import { asFunction } from 'awilix'\n * import { createOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock'\n *\n * container.register({\n *   crudMutationGuardService: asFunction((cradle) => createOptimisticLockGuardService({\n *     getEm: () => cradle.em,\n *     readers: {\n *       'customers.company': async (em, { resourceId, tenantId }) => {\n *         const row = await em.findOne(Company, { id: resourceId, tenantId }, { fields: ['updatedAt'] })\n *         return row?.updatedAt ? row.updatedAt.toISOString() : null\n *       },\n *     },\n *   })).singleton(),\n * })\n * ```\n */\nexport function createOptimisticLockGuardService(\n  opts: OptimisticLockGuardOptions,\n): OptimisticLockGuardService {\n  const envValue = opts.envValue !== undefined ? opts.envValue : process.env[OPTIMISTIC_LOCK_ENV_VAR]\n  const config = parseOptimisticLockEnv(envValue)\n  const resolveExpected = opts.resolveExpected ?? defaultResolveExpectedUpdatedAt\n  const debugEnabled = process.env.OM_OPTIMISTIC_LOCK_DEBUG === '1'\n\n  function isEntityEnabled(resourceKind: string): boolean {\n    if (config.mode === 'off') return false\n    if (config.mode === 'all') return true\n    return config.entities.has(resourceKind.toLowerCase())\n  }\n\n  async function validateMutation(\n    input: CrudMutationGuardValidateInput,\n  ): Promise<CrudMutationGuardValidationResult> {\n    if (config.mode === 'off') {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n    if (input.operation !== 'update' && input.operation !== 'delete') {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n    if (!isEntityEnabled(input.resourceKind)) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n    const readers = opts.readers ?? getAllOptimisticLockReaders()\n    const reader = readers[input.resourceKind]\n    if (!reader) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n\n    const expectedRaw = readHeader(input.requestHeaders, OPTIMISTIC_LOCK_HEADER_NAME)\n    const resolvedExpected = await resolveExpected({\n      expectedFromHeader: expectedRaw,\n      resourceKind: input.resourceKind,\n      resourceId: input.resourceId,\n    })\n    if (resolvedExpected == null) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n\n    const expectedIso = normalizeIsoToken(resolvedExpected)\n    if (expectedIso == null) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n\n    const em = opts.getEm()\n    const currentRaw = await reader(em, {\n      resourceKind: input.resourceKind,\n      resourceId: input.resourceId,\n      tenantId: input.tenantId,\n      organizationId: input.organizationId ?? null,\n    })\n    if (currentRaw == null) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n    const currentIso = normalizeIsoToken(currentRaw)\n    if (currentIso == null) {\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n\n    if (currentIso === expectedIso) {\n      if (debugEnabled) {\n        // eslint-disable-next-line no-console\n        console.log('[optimistic-lock] match', {\n          resourceKind: input.resourceKind,\n          resourceId: input.resourceId,\n          operation: input.operation,\n          currentIso,\n          expectedIso,\n        })\n      }\n      return { ok: true, shouldRunAfterSuccess: false }\n    }\n\n    if (debugEnabled) {\n      // eslint-disable-next-line no-console\n      console.log('[optimistic-lock] CONFLICT', {\n        resourceKind: input.resourceKind,\n        resourceId: input.resourceId,\n        operation: input.operation,\n        tenantId: input.tenantId,\n        organizationId: input.organizationId ?? null,\n        expectedRaw: resolvedExpected,\n        expectedIso,\n        currentRaw,\n        currentIso,\n      })\n    }\n\n    return {\n      ok: false,\n      status: 409,\n      body: buildConflictBody(currentIso, expectedIso),\n    }\n  }\n\n  async function afterMutationSuccess(_input: CrudMutationGuardAfterSuccessInput): Promise<void> {\n    // no-op: optimistic check has no post-success cleanup\n  }\n\n  function getConfig(): OptimisticLockConfig {\n    return config\n  }\n\n  return {\n    validateMutation,\n    afterMutationSuccess,\n    getConfig,\n  }\n}\n"],
-  "mappings": "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",
-  "names": []
-}

package/src/lib/crud/__tests__/optimistic-lock-command.test.ts

@@ -1,425 +0,0 @@
-import {
-  assertOptimisticLock,
-  buildOptimisticLockConflictBody,
-  createCommandOptimisticLockGuardService,
-  enforceCommandOptimisticLock,
-  enforceRecordGoneIsConflict,
-  readOptimisticLockExpected,
-} from '../optimistic-lock-command'
-import { CrudHttpError, isCrudHttpError } from '../errors'
-import {
-  OPTIMISTIC_LOCK_CONFLICT_CODE,
-  OPTIMISTIC_LOCK_CONFLICT_ERROR,
-  OPTIMISTIC_LOCK_HEADER_NAME,
-} from '../optimistic-lock-headers'
-
-const A = '2026-05-25T08:42:18.123Z'
-const B = '2026-05-25T08:42:20.999Z'
-
-function headersWith(token: string | null): Headers {
-  const h = new Headers()
-  if (token != null) h.set(OPTIMISTIC_LOCK_HEADER_NAME, token)
-  return h
-}
-
-describe('readOptimisticLockExpected', () => {
-  it('reads + trims the header from a Headers object', () => {
-    expect(readOptimisticLockExpected(headersWith(`  ${A}  `))).toBe(A)
-  })
-
-  it('reads the header from a Request', () => {
-    const req = new Request('https://example.test/api/sales/order-lines', {
-      method: 'PUT',
-      headers: headersWith(A),
-    })
-    expect(readOptimisticLockExpected(req)).toBe(A)
-  })
-
-  it('returns null when the header is absent / empty / source missing', () => {
-    expect(readOptimisticLockExpected(headersWith(null))).toBeNull()
-    expect(readOptimisticLockExpected(headersWith('   '))).toBeNull()
-    expect(readOptimisticLockExpected(null)).toBeNull()
-    expect(readOptimisticLockExpected(undefined)).toBeNull()
-  })
-})
-
-describe('assertOptimisticLock', () => {
-  it('throws 409 with the structured body on a version mismatch', () => {
-    let caught: unknown
-    try {
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: B,
-        envValue: 'all',
-      })
-    } catch (err) {
-      caught = err
-    }
-    expect(isCrudHttpError(caught)).toBe(true)
-    const httpError = caught as CrudHttpError
-    expect(httpError.status).toBe(409)
-    expect(httpError.body).toEqual({
-      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
-      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
-      currentUpdatedAt: B,
-      expectedUpdatedAt: A,
-    })
-  })
-
-  it('passes when expected matches current (normalized comparison across Date + string)', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: new Date(A),
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('is a no-op when no expected token is supplied (strictly additive)', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: null,
-        current: B,
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: '   ',
-        current: B,
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('is a no-op when the current version is missing (let the command 404)', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: null,
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('is a no-op when expected is an unparseable token', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: 'not-a-date',
-        current: B,
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('respects OM_OPTIMISTIC_LOCK=off (no 409 even on mismatch)', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: B,
-        envValue: 'off',
-      }),
-    ).not.toThrow()
-  })
-
-  it('respects an allow-list that excludes the resourceKind', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: B,
-        envValue: 'customers.company',
-      }),
-    ).not.toThrow()
-  })
-
-  it('enforces the check for a resourceKind present in the allow-list', () => {
-    expect(() =>
-      assertOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        expected: A,
-        current: B,
-        envValue: 'sales.order',
-      }),
-    ).toThrow(CrudHttpError)
-  })
-
-  it('is ON by default (env unset) — mismatch 409s', () => {
-    const prev = process.env.OM_OPTIMISTIC_LOCK
-    delete process.env.OM_OPTIMISTIC_LOCK
-    try {
-      expect(() =>
-        assertOptimisticLock({
-          resourceKind: 'sales.order',
-          resourceId: 'order-1',
-          expected: A,
-          current: B,
-        }),
-      ).toThrow(CrudHttpError)
-    } finally {
-      if (prev !== undefined) process.env.OM_OPTIMISTIC_LOCK = prev
-    }
-  })
-})
-
-describe('enforceCommandOptimisticLock', () => {
-  it('reads the expected token from the request header and 409s on mismatch', () => {
-    const req = new Request('https://example.test/api/sales/order-lines', {
-      method: 'PUT',
-      headers: headersWith(A),
-    })
-    expect(() =>
-      enforceCommandOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        request: req,
-        envValue: 'all',
-      }),
-    ).toThrow(CrudHttpError)
-  })
-
-  it('prefers the explicit expected override over the header', () => {
-    const req = new Request('https://example.test/api/sales/order-lines', {
-      method: 'PUT',
-      headers: headersWith(B), // header matches current → would pass if used
-    })
-    expect(() =>
-      enforceCommandOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        expected: A, // stale override → must 409
-        request: req,
-        envValue: 'all',
-      }),
-    ).toThrow(CrudHttpError)
-  })
-
-  it('is a no-op when neither override nor header is present', () => {
-    expect(() =>
-      enforceCommandOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        request: headersWith(null),
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('passes when the header matches the current version', () => {
-    expect(() =>
-      enforceCommandOptimisticLock({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: new Date(A),
-        request: headersWith(A),
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-})
-
-describe('enforceRecordGoneIsConflict', () => {
-  it('409s when the client opted in (header present) but the record is gone', () => {
-    let caught: unknown
-    try {
-      enforceRecordGoneIsConflict({
-        resourceKind: 'customers.interaction',
-        resourceId: 'int-1',
-        request: headersWith(A),
-        envValue: 'all',
-      })
-    } catch (err) {
-      caught = err
-    }
-    expect(isCrudHttpError(caught)).toBe(true)
-    const httpError = caught as CrudHttpError
-    expect(httpError.status).toBe(409)
-    // No current version exists for a deleted record, so it echoes the expected token.
-    expect(httpError.body).toEqual({
-      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
-      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
-      currentUpdatedAt: A,
-      expectedUpdatedAt: A,
-    })
-  })
-
-  it('is a no-op when the client did not opt in (no header → caller 404 fires)', () => {
-    expect(() =>
-      enforceRecordGoneIsConflict({
-        resourceKind: 'customers.interaction',
-        resourceId: 'int-1',
-        request: headersWith(null),
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-
-  it('prefers an explicit expected override over the header', () => {
-    expect(() =>
-      enforceRecordGoneIsConflict({
-        resourceKind: 'customers.interaction',
-        resourceId: 'int-1',
-        expected: A,
-        request: headersWith(null),
-        envValue: 'all',
-      }),
-    ).toThrow(CrudHttpError)
-  })
-
-  it('is a no-op when the env disables the guard for the resource', () => {
-    expect(() =>
-      enforceRecordGoneIsConflict({
-        resourceKind: 'customers.interaction',
-        resourceId: 'int-1',
-        request: headersWith(A),
-        envValue: 'off',
-      }),
-    ).not.toThrow()
-  })
-
-  it('is a no-op when the expected token is unparseable', () => {
-    expect(() =>
-      enforceRecordGoneIsConflict({
-        resourceKind: 'customers.interaction',
-        resourceId: 'int-1',
-        request: headersWith('not-a-date'),
-        envValue: 'all',
-      }),
-    ).not.toThrow()
-  })
-})
-
-describe('buildOptimisticLockConflictBody', () => {
-  it('shapes the structured conflict body', () => {
-    expect(buildOptimisticLockConflictBody(B, A)).toEqual({
-      error: OPTIMISTIC_LOCK_CONFLICT_ERROR,
-      code: OPTIMISTIC_LOCK_CONFLICT_CODE,
-      currentUpdatedAt: B,
-      expectedUpdatedAt: A,
-    })
-  })
-})
-
-describe('createCommandOptimisticLockGuardService', () => {
-  it('default service mirrors enforceCommandOptimisticLock (header compare → 409 on mismatch)', async () => {
-    const guard = createCommandOptimisticLockGuardService()
-    let caught: unknown
-    try {
-      await guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        request: headersWith(A),
-        envValue: 'all',
-      })
-    } catch (err) {
-      caught = err
-    }
-    expect(isCrudHttpError(caught)).toBe(true)
-    expect((caught as CrudHttpError).status).toBe(409)
-  })
-
-  it('default service is a no-op when the client sends no expected token (strictly additive)', async () => {
-    const guard = createCommandOptimisticLockGuardService()
-    await expect(
-      guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        request: headersWith(null),
-        envValue: 'all',
-      }),
-    ).resolves.toBeUndefined()
-  })
-
-  it('default service is a no-op when the env disables the guard for the resource', async () => {
-    const guard = createCommandOptimisticLockGuardService()
-    await expect(
-      guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-1',
-        current: B,
-        request: headersWith(A),
-        envValue: 'off',
-      }),
-    ).resolves.toBeUndefined()
-  })
-
-  it('resolveExpected overrides the header-derived token (enterprise extension point)', async () => {
-    const seen: Array<{ expectedFromHeader: string | null; resourceKind: string; resourceId: string }> = []
-    // Resolver supplies a stale token even though the client header matches `current`,
-    // proving enterprise can drive the expected version from a lock record.
-    const guard = createCommandOptimisticLockGuardService({
-      resolveExpected: (input) => {
-        seen.push(input)
-        return A
-      },
-    })
-    let caught: unknown
-    try {
-      await guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-9',
-        current: B,
-        request: headersWith(B),
-        envValue: 'all',
-      })
-    } catch (err) {
-      caught = err
-    }
-    expect(isCrudHttpError(caught)).toBe(true)
-    expect((caught as CrudHttpError).status).toBe(409)
-    expect(seen).toHaveLength(1)
-    expect(seen[0]).toEqual({ expectedFromHeader: B, resourceKind: 'sales.order', resourceId: 'order-9' })
-  })
-
-  it('awaits an async resolveExpected and passes when it returns the current token', async () => {
-    const guard = createCommandOptimisticLockGuardService({
-      resolveExpected: async () => B,
-    })
-    await expect(
-      guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-9',
-        current: B,
-        request: headersWith(A),
-        envValue: 'all',
-      }),
-    ).resolves.toBeUndefined()
-  })
-
-  it('resolveExpected returning null skips the check (no expected → additive no-op)', async () => {
-    const guard = createCommandOptimisticLockGuardService({
-      resolveExpected: () => null,
-    })
-    await expect(
-      guard.enforce({
-        resourceKind: 'sales.order',
-        resourceId: 'order-9',
-        current: B,
-        request: headersWith(A),
-        envValue: 'all',
-      }),
-    ).resolves.toBeUndefined()
-  })
-})