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

package/src/lib/crud/optimistic-lock.ts

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

package/src/lib/data/engine.ts

@@ -572,10 +572,12 @@ export class DefaultDataEngine implements DataEngine {
         enrichedPayload.crudAction = action
         if (coverageBaseDelta !== undefined) enrichedPayload.coverageBaseDelta = coverageBaseDelta
         if (ctx.syncOrigin) enrichedPayload.syncOrigin = ctx.syncOrigin
-        // Fire-and-forget: token reindexing runs DELETE + chunked INSERT against
-        // search_tokens and would otherwise block the HTTP response on every write.
-        // Surrender control after queueing the emit; index updates settle out-of-band.
-        void bus.emitEvent('query_index.delete_one', enrichedPayload).catch((err: unknown) => {
+        // Await the index update so query-index reads (the `customValues`/scalar
+        // projection that list endpoints serve) are consistent the moment the write
+        // returns. The subscriber removes the projection row + tokens synchronously and
+        // defers the coverage recompute + fulltext delete, so this stays bounded.
+        // Errors are logged, not thrown — index drift never fails the originating write.
+        await bus.emitEvent('query_index.delete_one', enrichedPayload).catch((err: unknown) => {
           console.error('[data-engine] query_index.delete_one emit failed', err)
         })
       } else {
@@ -591,10 +593,11 @@ export class DefaultDataEngine implements DataEngine {
         enrichedPayload.crudAction = action
         if (coverageBaseDelta !== undefined) enrichedPayload.coverageBaseDelta = coverageBaseDelta
         if (ctx.syncOrigin) enrichedPayload.syncOrigin = ctx.syncOrigin
-        // Fire-and-forget: see delete_one above. Token reindexing pipeline
-        // (build doc + encrypt + decrypt + tokenize + DELETE + chunked INSERT)
-        // would otherwise serialize into write request latency.
-        void bus.emitEvent('query_index.upsert_one', enrichedPayload).catch((err: unknown) => {
+        // Await the projection upsert so list reads observe the new doc immediately
+        // (see delete_one above). The subscriber updates `entity_indexes` synchronously
+        // and defers the heavy token-reindex pipeline (build doc + encrypt + decrypt +
+        // tokenize + DELETE + chunked INSERT) so write latency stays bounded.
+        await bus.emitEvent('query_index.upsert_one', enrichedPayload).catch((err: unknown) => {
           console.error('[data-engine] query_index.upsert_one emit failed', err)
         })
       }

package/src/lib/di/container.ts

@@ -1,4 +1,4 @@
-import { createContainer, asValue, AwilixContainer, InjectionMode, type Resolver } from 'awilix'
+import { asFunction, createContainer, asValue, AwilixContainer, InjectionMode, type Resolver } from 'awilix'
 import { RequestContext } from '@mikro-orm/core'
 import { getOrm } from '@open-mercato/shared/lib/db/mikro'
 import { EntityManager } from '@mikro-orm/postgresql'
@@ -6,6 +6,8 @@ import { BasicQueryEngine } from '@open-mercato/shared/lib/query/engine'
 import { DefaultDataEngine } from '@open-mercato/shared/lib/data/engine'
 import { commandRegistry, CommandBus } from '@open-mercato/shared/lib/commands'
 import { applyDiOverridesToContainer } from '@open-mercato/shared/modules/overrides'
+import { createOptimisticLockGuardService } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { getAllOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 
 type DynamicCradle = Record<string, any>
 
@@ -155,6 +157,20 @@ export async function createRequestContainer(): Promise<AppContainer> {
     dataEngine: asValue(new DefaultDataEngine(em, container as any)),
     commandRegistry: asValue(commandRegistry),
     commandBus: asValue(new CommandBus()),
+    // Default OSS optimistic-lock guard. Reads from the global reader store
+    // (populated by `makeCrudRoute` auto-registration + any module-DI
+    // hand-wired calls to `registerOptimisticLockReaders`). Service is
+    // strictly additive: when `OM_OPTIMISTIC_LOCK=off` (or no header is
+    // sent) it short-circuits at validateMutation. Module-level di.ts
+    // registrations override this default via Awilix replace semantics —
+    // see the enterprise `record_locks` module for the canonical override.
+    // Spec: .ai/specs/2026-05-25-oss-optimistic-locking.md
+    crudMutationGuardService: asFunction(({ em: scopedEm }: { em: EntityManager }) =>
+      createOptimisticLockGuardService({
+        getEm: () => scopedEm,
+        readers: getAllOptimisticLockReaders(),
+      }),
+    ).scoped(),
   })
   // Allow modules to override/extend
   for (const reg of diRegistrars) {

package/src/lib/encryption/__tests__/dek-lifecycle.test.ts

@@ -0,0 +1,194 @@
+import { decryptWithAesGcm, generateDek } from '../aes'
+import { HashicorpVaultKmsService, type KmsService, type TenantDek } from '../kms'
+import { TenantDataEncryptionService } from '../tenantDataEncryptionService'
+
+const originalEnv = { ...process.env }
+
+type DuckResponse = { ok: boolean; status: number; json: () => Promise<unknown> }
+
+function jsonResponse(status: number, body: Record<string, unknown>): DuckResponse {
+  return { ok: status >= 200 && status < 300, status, json: async () => body }
+}
+
+// Minimal in-memory Vault KV v2 simulator: GET reads the stored key, POST writes
+// it unless a `cas: 0` write loses to an existing version (concurrent create).
+function makeVaultSim() {
+  const store = new Map<string, string>()
+  const counts = { reads: 0, posts: 0, persisted: 0 }
+  const fetchMock = jest.fn(async (input: unknown, init?: RequestInit): Promise<DuckResponse> => {
+    const url = String(input)
+    const path = url.slice(url.indexOf('/v1/') + '/v1/'.length)
+    const method = (init?.method || 'GET').toUpperCase()
+    if (method === 'GET') {
+      counts.reads++
+      const key = store.get(path)
+      if (!key) return jsonResponse(404, { errors: [] })
+      return jsonResponse(200, { data: { data: { key } } })
+    }
+    counts.posts++
+    const body = init?.body ? (JSON.parse(String(init.body)) as { data?: { key?: string }; options?: { cas?: number } }) : {}
+    const cas = body.options?.cas
+    if (cas === 0 && store.has(path)) {
+      return jsonResponse(400, { errors: ['check-and-set parameter did not match the current version'] })
+    }
+    store.set(path, body.data?.key ?? '')
+    counts.persisted++
+    return jsonResponse(200, { data: { version: 1 } })
+  })
+  return { store, counts, fetchMock }
+}
+
+function installFetch(fetchMock: jest.Mock) {
+  ;(globalThis as { fetch?: typeof fetch }).fetch = fetchMock as unknown as typeof fetch
+}
+
+const fixedKey = (fill: number) => Buffer.alloc(32, fill).toString('base64')
+
+describe('HashicorpVaultKmsService DEK creation race (issue #2746)', () => {
+  afterEach(() => {
+    process.env = { ...originalEnv }
+    jest.restoreAllMocks()
+  })
+
+  it('reuses an existing Vault DEK instead of overwriting it (read-before-write)', async () => {
+    const { store, counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+    const existingKey = fixedKey(7)
+    store.set('secret/data/tenant_key_tenant-existing', existingKey)
+
+    const dek = await service.createTenantDek('tenant-existing')
+
+    expect(dek?.key).toBe(existingKey)
+    expect(counts.persisted).toBe(0) // never overwrote the active key
+  })
+
+  it('converges concurrent createTenantDek calls on a single key via CAS', async () => {
+    const { counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+
+    const [a, b] = await Promise.all([
+      service.createTenantDek('tenant-cas'),
+      service.createTenantDek('tenant-cas'),
+    ])
+
+    expect(a?.key).toBeTruthy()
+    expect(a?.key).toBe(b?.key) // both adopt the same winning key — no orphaned rows
+    expect(counts.persisted).toBe(1) // exactly one key persisted, last-write-wins eliminated
+  })
+
+  it('invalidateDek forces a re-read from Vault', async () => {
+    const { store, counts, fetchMock } = makeVaultSim()
+    installFetch(fetchMock)
+    const service = new HashicorpVaultKmsService({ vaultAddr: 'http://vault.test', vaultToken: 'token' })
+    const path = 'secret/data/tenant_key_tenant-inv'
+    store.set(path, fixedKey(3))
+
+    const first = await service.getTenantDek('tenant-inv')
+    await service.getTenantDek('tenant-inv') // served from the KMS TTL cache
+    expect(counts.reads).toBe(1)
+
+    store.set(path, fixedKey(9)) // operator rotates the key in Vault
+    service.invalidateDek('tenant-inv')
+    const rotated = await service.getTenantDek('tenant-inv')
+
+    expect(counts.reads).toBe(2)
+    expect(rotated?.key).not.toBe(first?.key)
+  })
+})
+
+describe('TenantDataEncryptionService DEK lifecycle (issue #2746)', () => {
+  const entityId = 'customers:person'
+  let tenantSeq = 0
+  const uniqueTenant = (label: string) => `tenant-${label}-2746-${tenantSeq++}`
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  function makeCreatingKms() {
+    const created: string[] = []
+    const kms: KmsService = {
+      isHealthy: () => true,
+      getTenantDek: jest.fn(async (): Promise<TenantDek | null> => null),
+      createTenantDek: jest.fn(async (tenantId: string): Promise<TenantDek | null> => {
+        const key = generateDek()
+        created.push(key)
+        return { tenantId, key, fetchedAt: Date.now() }
+      }),
+    }
+    return { kms, created }
+  }
+
+  function makeFetchingKms() {
+    const kms: KmsService = {
+      isHealthy: () => true,
+      getTenantDek: jest.fn(async (tenantId: string): Promise<TenantDek | null> => ({
+        tenantId,
+        key: generateDek(),
+        fetchedAt: Date.now(),
+      })),
+      createTenantDek: jest.fn(async (): Promise<TenantDek | null> => null),
+    }
+    return { kms }
+  }
+
+  it('dedupes concurrent first-time DEK creation so no row is orphaned', async () => {
+    const { kms, created } = makeCreatingKms()
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    jest.spyOn(service, 'isEnabled').mockReturnValue(true)
+    ;(service as unknown as { getMap: () => Promise<{ entityId: string; fields: { field: string }[] }> }).getMap =
+      jest.fn(async () => ({ entityId, fields: [{ field: 'secret' }] }))
+    const tenantId = uniqueTenant('race')
+
+    const rows = await Promise.all(
+      Array.from({ length: 12 }, (_, i) =>
+        service.encryptEntityPayload(entityId, { secret: `value-${i}` }, tenantId),
+      ),
+    )
+
+    expect((kms.createTenantDek as jest.Mock)).toHaveBeenCalledTimes(1)
+    expect(new Set(created).size).toBe(1)
+
+    const dek = await service.getDek(tenantId)
+    expect(dek).not.toBeNull()
+    rows.forEach((row, i) => {
+      expect(decryptWithAesGcm(String(row.secret), (dek as TenantDek).key)).toBe(`value-${i}`)
+    })
+  })
+
+  it('re-fetches a cached DEK after the TTL elapses (no stale key after rotation)', async () => {
+    const { kms } = makeFetchingKms()
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    const tenantId = uniqueTenant('ttl')
+    let now = 1_700_000_000_000
+    jest.spyOn(Date, 'now').mockImplementation(() => now)
+
+    await service.getDek(tenantId)
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(1) // cached within TTL
+
+    now += 15 * 60 * 1000 + 1
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(2) // expired → re-fetch
+  })
+
+  it('invalidateDek clears both the service cache and the KMS cache', async () => {
+    const { kms } = makeFetchingKms()
+    const kmsInvalidate = jest.fn()
+    ;(kms as KmsService).invalidateDek = kmsInvalidate
+    const service = new TenantDataEncryptionService({} as never, { kms })
+    const tenantId = uniqueTenant('invalidate')
+
+    await service.getDek(tenantId)
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(1)
+
+    service.invalidateDek(tenantId)
+    expect(kmsInvalidate).toHaveBeenCalledWith(tenantId)
+
+    await service.getDek(tenantId)
+    expect((kms.getTenantDek as jest.Mock)).toHaveBeenCalledTimes(2)
+  })
+})