@open-mercato/core 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/ecommerce/lib/cacheInvalidation.ts

@@ -0,0 +1,302 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import {
+  catalogCategoryTag,
+  catalogPriceTag,
+  catalogProductTag,
+  catalogProductsTag,
+  ecommerceCustomerGroupTag,
+  ecommerceCustomerTag,
+  ecommerceCustomerUserTag,
+  ecommerceDomainMappingTag,
+  ecommerceDomainTag,
+  ecommerceStoreTag,
+  ecommerceUngroupedBuyerTag,
+  invalidateEcommerceCacheTags,
+  storefrontAvailabilityTag,
+} from './cacheKeys'
+import {
+  asPayloadRecord,
+  eventAction,
+  readEventScope,
+  readPayloadString,
+  tryResolveService,
+  type EcommerceSubscriberContext,
+} from './subscriberSupport'
+
+/**
+ * Event → cache-tag mapping for the storefront caches (SPEC-029 §8 table). Every eviction goes
+ * through `invalidateEcommerceCacheTags`, which clears the tenant-agnostic resolution cache and the
+ * emitting tenant's buyer/storefront caches.
+ */
+
+const logger = createLogger('ecommerce').child({ component: 'cache-invalidation' })
+
+type TagDeriver = (payload: Record<string, unknown>, action: string | null, tenantId: string | null) => string[]
+
+const STORE_CACHE_ACTIONS: ReadonlySet<string> = new Set(['created', 'updated', 'deleted', 'branding_updated'])
+const CUSTOMER_GROUP_CACHE_ACTIONS: ReadonlySet<string> = new Set(['created', 'updated', 'deleted'])
+const CUSTOMER_GROUP_DEFAULT_CANDIDATE_ACTIONS: ReadonlySet<string> = new Set(['created', 'updated'])
+const CATALOG_CRUD_ACTIONS: ReadonlySet<string> = new Set(['created', 'updated', 'deleted'])
+const CUSTOMER_USER_CACHE_ACTIONS: ReadonlySet<string> = new Set(['updated', 'deleted'])
+
+function tagsFrom(values: Array<string | null>, toTag: (value: string) => string): string[] {
+  return values.filter((value): value is string => value !== null).map(toTag)
+}
+
+export const storeEventTags: TagDeriver = (payload, action) => {
+  if (action && !STORE_CACHE_ACTIONS.has(action)) return []
+  return tagsFrom([readPayloadString(payload, 'id')], ecommerceStoreTag)
+}
+
+export const storeDomainBindingEventTags: TagDeriver = (payload) => [
+  ...tagsFrom(
+    [readPayloadString(payload, 'storeId'), readPayloadString(payload, 'previousStoreId')],
+    ecommerceStoreTag,
+  ),
+  ...tagsFrom(
+    [readPayloadString(payload, 'domainMappingId'), readPayloadString(payload, 'previousDomainMappingId')],
+    ecommerceDomainMappingTag,
+  ),
+]
+
+export const storeChannelBindingEventTags: TagDeriver = (payload) =>
+  tagsFrom([readPayloadString(payload, 'storeId'), readPayloadString(payload, 'previousStoreId')], ecommerceStoreTag)
+
+export const domainMappingEventTags: TagDeriver = (payload) => [
+  ...tagsFrom(
+    [readPayloadString(payload, 'id'), readPayloadString(payload, 'replacedDomainId')],
+    ecommerceDomainMappingTag,
+  ),
+  ...tagsFrom(
+    [readPayloadString(payload, 'hostname'), readPayloadString(payload, 'replacedHostname')],
+    ecommerceDomainTag,
+  ),
+]
+
+/**
+ * `customer_accounts.user.updated|deleted`: the user's buyer contexts, so a deactivated or deleted
+ * portal user stops resolving to their cached identity (and contract prices) before the TTL ends.
+ */
+export const customerUserEventTags: TagDeriver = (payload, action) => {
+  if (action && !CUSTOMER_USER_CACHE_ACTIONS.has(action)) return []
+  return tagsFrom([readPayloadString(payload, 'id')], ecommerceCustomerUserTag)
+}
+
+export const customerGroupMembershipEventTags: TagDeriver = (payload) =>
+  tagsFrom([readPayloadString(payload, 'customerId')], ecommerceCustomerTag)
+
+/**
+ * `customer_groups.group.*`: the group's buyer contexts. The payload carries no `isDefault`, so a
+ * create or update also evicts the tenant's ungrouped buyer contexts, which would fall back to the
+ * group if it became the tenant default; a replaced default is announced as its own update.
+ */
+export const customerGroupEventTags: TagDeriver = (payload, action, tenantId) => {
+  if (action && !CUSTOMER_GROUP_CACHE_ACTIONS.has(action)) return []
+  const tags = action === 'created' ? [] : tagsFrom([readPayloadString(payload, 'id')], ecommerceCustomerGroupTag)
+  if (tenantId && (!action || CUSTOMER_GROUP_DEFAULT_CANDIDATE_ACTIONS.has(action))) {
+    tags.push(ecommerceUngroupedBuyerTag(tenantId))
+  }
+  return tags
+}
+
+export const customerGroupTermsEventTags: TagDeriver = (payload) =>
+  tagsFrom([readPayloadString(payload, 'groupId')], ecommerceCustomerGroupTag)
+
+export async function invalidateForEvent(
+  payload: unknown,
+  ctx: EcommerceSubscriberContext,
+  deriveTags: TagDeriver,
+): Promise<number> {
+  const record = asPayloadRecord(payload)
+  const { tenantId } = readEventScope(record, ctx)
+  const tags = deriveTags(record, eventAction(ctx.eventName), tenantId)
+  if (tags.length === 0) return 0
+  return invalidateEcommerceCacheTags(ctx, { tenantId, tags })
+}
+
+type CatalogLookupDatabase = {
+  catalog_product_variant_prices: {
+    id: string
+    tenant_id: string
+    organization_id: string
+    customer_id: string | null
+    product_id: string | null
+    variant_id: string | null
+  }
+  catalog_product_variants: {
+    id: string
+    tenant_id: string
+    organization_id: string
+    product_id: string
+  }
+  availability_policies: {
+    id: string
+    tenant_id: string
+    organization_id: string
+    product_id: string | null
+  }
+}
+
+type PriceOwner = { customerId: string | null; productId: string | null }
+
+type LookupScope = { tenantId: string; organizationId: string | null }
+
+async function readPriceOwner(em: EntityManager, priceId: string, scope: LookupScope): Promise<PriceOwner | null> {
+  let query = em
+    .getKysely<CatalogLookupDatabase>()
+    .selectFrom('catalog_product_variant_prices as price')
+    .leftJoin('catalog_product_variants as variant', 'variant.id', 'price.variant_id')
+    .select(['price.customer_id as customerId', 'price.product_id as productId', 'variant.product_id as variantProductId'])
+    .where('price.id', '=', priceId)
+    .where('price.tenant_id', '=', scope.tenantId)
+  if (scope.organizationId) query = query.where('price.organization_id', '=', scope.organizationId)
+  const row = await query.executeTakeFirst()
+  if (!row) return null
+  return { customerId: row.customerId ?? null, productId: row.productId ?? row.variantProductId ?? null }
+}
+
+async function readVariantProductId(em: EntityManager, variantId: string, scope: LookupScope): Promise<string | null> {
+  let query = em
+    .getKysely<CatalogLookupDatabase>()
+    .selectFrom('catalog_product_variants')
+    .select('product_id')
+    .where('id', '=', variantId)
+    .where('tenant_id', '=', scope.tenantId)
+  if (scope.organizationId) query = query.where('organization_id', '=', scope.organizationId)
+  const row = await query.executeTakeFirst()
+  return row?.product_id ?? null
+}
+
+async function readPolicyProductId(em: EntityManager, policyId: string, scope: LookupScope): Promise<string | null> {
+  let query = em
+    .getKysely<CatalogLookupDatabase>()
+    .selectFrom('availability_policies')
+    .select('product_id')
+    .where('id', '=', policyId)
+    .where('tenant_id', '=', scope.tenantId)
+  if (scope.organizationId) query = query.where('organization_id', '=', scope.organizationId)
+  const row = await query.executeTakeFirst()
+  return row?.product_id ?? null
+}
+
+/**
+ * Reads the row an id-only catalog/availability payload points at. A missing `em`, a missing row
+ * and a failed lookup all answer `undefined`, so the caller falls back to its broader tag.
+ */
+async function lookupForEvent<T>(
+  ctx: EcommerceSubscriberContext,
+  id: string,
+  scope: LookupScope,
+  lookup: (em: EntityManager, id: string, scope: LookupScope) => Promise<T | null>,
+  failureCode: string,
+): Promise<T | undefined> {
+  const em = tryResolveService<EntityManager>(ctx, 'em')
+  if (!em) return undefined
+  try {
+    return (await lookup(em, id, scope)) ?? undefined
+  } catch (error) {
+    logger.warn('Storefront cache lookup failed; falling back to broader tags', { id, failureCode, err: error })
+    getTelemetryRuntime()?.reportError(error, {
+      module: 'ecommerce',
+      code: failureCode,
+      attributes: { id },
+    })
+    return undefined
+  }
+}
+
+type ScopedEvent = { id: string; action: string | null; scope: LookupScope }
+
+function readScopedEvent(payload: unknown, ctx: EcommerceSubscriberContext): ScopedEvent | null {
+  const record = asPayloadRecord(payload)
+  const id = readPayloadString(record, 'id')
+  const scope = readEventScope(record, ctx)
+  if (!id || !scope.tenantId) return null
+  return { id, action: eventAction(ctx.eventName), scope: { tenantId: scope.tenantId, organizationId: scope.organizationId } }
+}
+
+function isCatalogCrudAction(action: string | null): boolean {
+  return action === null || CATALOG_CRUD_ACTIONS.has(action)
+}
+
+/**
+ * `catalog.price.*` (§8 buyer context, Storefront Public API §9): evicts the product's
+ * `catalog-price` tag and every listing of the tenant, plus the owning customer's buyer context
+ * when the row is customer-specific (`customerOverlayId`). The payload carries ids only, so the row
+ * is read back; a deleted row is gone, so a delete evicts the listings only and the product detail
+ * and buyer context fall back to their TTLs (catalog declares no price-kind events either).
+ */
+export async function invalidateForPriceEvent(payload: unknown, ctx: EcommerceSubscriberContext): Promise<number> {
+  const event = readScopedEvent(payload, ctx)
+  if (!event || !isCatalogCrudAction(event.action)) return 0
+  const owner =
+    event.action === 'deleted'
+      ? undefined
+      : await lookupForEvent(ctx, event.id, event.scope, readPriceOwner, 'ecommerce.price_cache_invalidation_failed')
+  const tags = [catalogProductsTag(event.scope.tenantId)]
+  if (owner?.productId) tags.push(catalogPriceTag(owner.productId))
+  if (owner?.customerId) tags.push(ecommerceCustomerTag(owner.customerId))
+  return invalidateEcommerceCacheTags(ctx, { tenantId: event.scope.tenantId, tags })
+}
+
+/** `catalog.product.created|updated|deleted`: the product's detail entries and every listing of the tenant. */
+export async function invalidateForProductEvent(payload: unknown, ctx: EcommerceSubscriberContext): Promise<number> {
+  const event = readScopedEvent(payload, ctx)
+  if (!event || !isCatalogCrudAction(event.action)) return 0
+  return invalidateEcommerceCacheTags(ctx, {
+    tenantId: event.scope.tenantId,
+    tags: [catalogProductTag(event.id), catalogProductsTag(event.scope.tenantId)],
+  })
+}
+
+/**
+ * `catalog.variant.*`: the variant's product (read back — the payload carries ids only) and every
+ * listing of the tenant. A deleted variant row is gone, so its product detail falls back to its TTL.
+ */
+export async function invalidateForVariantEvent(payload: unknown, ctx: EcommerceSubscriberContext): Promise<number> {
+  const event = readScopedEvent(payload, ctx)
+  if (!event || !isCatalogCrudAction(event.action)) return 0
+  const productId =
+    event.action === 'deleted'
+      ? undefined
+      : await lookupForEvent(ctx, event.id, event.scope, readVariantProductId, 'ecommerce.variant_cache_invalidation_failed')
+  const tags = [catalogProductsTag(event.scope.tenantId)]
+  if (productId) tags.push(catalogProductTag(productId))
+  return invalidateEcommerceCacheTags(ctx, { tenantId: event.scope.tenantId, tags })
+}
+
+/** `catalog.category.*`: details showing the category and every listing (category names, filters, assortment). */
+export async function invalidateForCategoryEvent(payload: unknown, ctx: EcommerceSubscriberContext): Promise<number> {
+  const event = readScopedEvent(payload, ctx)
+  if (!event || !isCatalogCrudAction(event.action)) return 0
+  return invalidateEcommerceCacheTags(ctx, {
+    tenantId: event.scope.tenantId,
+    tags: [catalogCategoryTag(event.id), catalogProductsTag(event.scope.tenantId)],
+  })
+}
+
+/**
+ * `availability.policy.*`: a policy tied to a product evicts that product and every listing; a
+ * store- or tenant-wide policy (or one that cannot be read back) evicts every storefront product
+ * entry of the tenant. Policies are soft-deleted, so a delete still reads back its product.
+ */
+export async function invalidateForAvailabilityPolicyEvent(
+  payload: unknown,
+  ctx: EcommerceSubscriberContext,
+): Promise<number> {
+  const event = readScopedEvent(payload, ctx)
+  if (!event || !isCatalogCrudAction(event.action)) return 0
+  const productId = await lookupForEvent(
+    ctx,
+    event.id,
+    event.scope,
+    readPolicyProductId,
+    'ecommerce.availability_policy_cache_invalidation_failed',
+  )
+  const tags = productId
+    ? [catalogProductTag(productId), catalogProductsTag(event.scope.tenantId)]
+    : [storefrontAvailabilityTag(event.scope.tenantId)]
+  return invalidateEcommerceCacheTags(ctx, { tenantId: event.scope.tenantId, tags })
+}

package/src/modules/ecommerce/lib/cacheKeys.ts

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto'
+import { runWithCacheTenant, type CacheStrategy } from '@open-mercato/cache'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+import type { BuyerContext, StoreContext } from './types'
+
+/**
+ * The ONLY file in the ecommerce module allowed to resolve the DI `cache` (SPEC-029 §6.1
+ * "Enforcement", D7). Every storefront key is built by `buildStorefrontCacheKey`; callers pass
+ * `parts`, never a raw key. `__tests__/no-raw-cache-access.test.ts` fails on any other access.
+ */
+
+export type StorefrontCacheScope = 'digest' | 'assortment' | 'priceScope' | 'store'
+
+export type StorefrontCacheKeyOptions = { scope?: StorefrontCacheScope }
+
+export type StorefrontCacheSetOptions = {
+  ttlMs: number
+  tags?: string[]
+  scope?: StorefrontCacheScope
+}
+
+export type StorefrontCache = {
+  get<T>(parts: string[], options?: StorefrontCacheKeyOptions): Promise<T | null>
+  set<T>(parts: string[], value: T, options: StorefrontCacheSetOptions): Promise<void>
+  deleteByTags(tags: string[]): Promise<number>
+}
+
+export type EcommerceResolutionCacheSetOptions = { ttlMs: number; tags?: string[] }
+
+/**
+ * Store-resolution cache (host/slug → store + default channel binding, §8.1 steps 3–5). It runs
+ * BEFORE a `StoreContext` exists, so it is tenant-agnostic and MUST NEVER carry buyer data.
+ */
+export type EcommerceResolutionCache = {
+  get<T>(parts: string[]): Promise<T | null>
+  set<T>(parts: string[], value: T, options: EcommerceResolutionCacheSetOptions): Promise<void>
+  deleteByTags(tags: string[]): Promise<number>
+}
+
+/**
+ * Buyer-context cache (§8, step 6): one entry per (store, customerUserId | anonymous), holding the
+ * locale-independent buyer layer only. Tagged per store, per portal user, per identity in
+ * `customerIds` and per contributing group so user, membership, terms, group and price events can
+ * evict it.
+ */
+export type BuyerContextCache = {
+  get(customerUserId: string | null): Promise<BuyerContext | null>
+  set(buyer: BuyerContext): Promise<void>
+  deleteByTags(tags: string[]): Promise<number>
+}
+
+export type BuyerContextCacheScope = { tenantId: string; storeId: string }
+
+export type CacheContainer = { resolve: (name: string) => unknown }
+
+export const BUYER_CONTEXT_TTL_MS = 60_000
+
+const STOREFRONT_KEY_NAMESPACE = 'ecommerce:storefront'
+const RESOLUTION_KEY_NAMESPACE = 'ecommerce:resolution'
+const BUYER_KEY_NAMESPACE = 'ecommerce:buyer'
+const ANONYMOUS_SEGMENT = 'anonymous'
+const NULL_SEGMENT = '-'
+
+const SCOPE_SEGMENTS: Record<StorefrontCacheScope, string> = {
+  digest: 'digest',
+  assortment: 'assortment',
+  priceScope: 'price-scope',
+  store: 'store',
+}
+
+const logger = createLogger('ecommerce').child({ component: 'storefront-cache' })
+
+function encodeSegment(value: string): string {
+  return encodeURIComponent(value)
+}
+
+function encodeParts(parts: string[]): string {
+  if (parts.length === 0) {
+    throw new Error('[internal] ecommerce cache keys require at least one part')
+  }
+  return parts.map(encodeSegment).join(':')
+}
+
+function scopeSegments(ctx: StoreContext, scope: StorefrontCacheScope): string[] {
+  const storeId = ctx.store.id
+  switch (scope) {
+    case 'digest':
+      return [storeId, ctx.digest]
+    case 'assortment':
+      return [storeId, ctx.effectiveLocale, ctx.buyer.assortmentScopeHash]
+    case 'priceScope':
+      return [storeId, ctx.buyer.priceScopeKey, ctx.buyer.customerOverlayId ?? NULL_SEGMENT]
+    case 'store':
+      return [storeId, ctx.effectiveLocale]
+  }
+}
+
+export function buildStorefrontCacheKey(
+  ctx: StoreContext,
+  parts: string[],
+  options?: StorefrontCacheKeyOptions,
+): string {
+  const scope = options?.scope ?? 'digest'
+  const prefix = [SCOPE_SEGMENTS[scope], ...scopeSegments(ctx, scope).map(encodeSegment)].join(':')
+  return `${STOREFRONT_KEY_NAMESPACE}:${prefix}:${encodeParts(parts)}`
+}
+
+function canonicalCacheValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalCacheValue)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter((entry) => entry[1] !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, entry]) => [key, canonicalCacheValue(entry)]),
+    )
+  }
+  return value
+}
+
+/** A fixed-length key part for a structured value: object keys sorted, `undefined` entries dropped, sha256-hashed. */
+export function storefrontCacheValueHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(canonicalCacheValue(value))).digest('hex')
+}
+
+export function buildEcommerceResolutionCacheKey(parts: string[]): string {
+  return `${RESOLUTION_KEY_NAMESPACE}:${encodeParts(parts)}`
+}
+
+export function buildBuyerContextCacheKey(storeId: string, customerUserId: string | null): string {
+  return `${BUYER_KEY_NAMESPACE}:${encodeParts([storeId, customerUserId ?? ANONYMOUS_SEGMENT])}`
+}
+
+export function ecommerceStoreTag(storeId: string): string {
+  return `ecommerce-store:${storeId}`
+}
+
+export function ecommerceDomainMappingTag(domainMappingId: string): string {
+  return `ecommerce-domain-mapping:${domainMappingId}`
+}
+
+export function ecommerceDomainTag(hostname: string): string {
+  return `ecommerce-domain:${hostname}`
+}
+
+export function ecommerceCustomerTag(customerId: string): string {
+  return `customer:${customerId}`
+}
+
+/** One portal user's buyer contexts: evicted when the user is updated (e.g. deactivated) or deleted. */
+export function ecommerceCustomerUserTag(customerUserId: string): string {
+  return `customer-user:${customerUserId}`
+}
+
+export function ecommerceCustomerGroupTag(customerGroupId: string): string {
+  return `customer-group:${customerGroupId}`
+}
+
+export function catalogProductTag(productId: string): string {
+  return `catalog-product:${productId}`
+}
+
+/** Every storefront listing of a tenant: evicted by any product, variant, category or price change. */
+export function catalogProductsTag(tenantId: string): string {
+  return `catalog-products:${tenantId}`
+}
+
+export function catalogCategoryTag(categoryId: string): string {
+  return `catalog-category:${categoryId}`
+}
+
+export function catalogPriceTag(productId: string): string {
+  return `catalog-price:${productId}`
+}
+
+/** Every storefront product entry of a tenant: evicted by an availability policy not tied to one product. */
+export function storefrontAvailabilityTag(tenantId: string): string {
+  return `availability:${tenantId}`
+}
+
+/**
+ * Buyer contexts of a tenant that resolved to no customer group (anonymous or unassigned buyers
+ * while the tenant has no default group): evicted when a group is created or updated, since that
+ * group may have become the default they fall back to.
+ */
+export function ecommerceUngroupedBuyerTag(tenantId: string): string {
+  return `customer-group-none:${tenantId}`
+}
+
+export function buyerContextTags(
+  buyer: Pick<BuyerContext, 'customerIds' | 'customerGroupIds'> & { customerUserId?: string | null },
+  tenantId?: string,
+): string[] {
+  return [
+    ...(buyer.customerUserId ? [ecommerceCustomerUserTag(buyer.customerUserId)] : []),
+    ...buyer.customerIds.map(ecommerceCustomerTag),
+    ...buyer.customerGroupIds.map(ecommerceCustomerGroupTag),
+    ...(tenantId && buyer.customerGroupIds.length === 0 ? [ecommerceUngroupedBuyerTag(tenantId)] : []),
+  ]
+}
+
+function resolveCacheService(container: CacheContainer | null | undefined): CacheStrategy | null {
+  if (!container?.resolve) return null
+  try {
+    const candidate = container.resolve('cache') as CacheStrategy | null | undefined
+    if (
+      candidate &&
+      typeof candidate.get === 'function' &&
+      typeof candidate.set === 'function' &&
+      typeof candidate.deleteByTags === 'function'
+    ) {
+      return candidate
+    }
+  } catch {
+    return null
+  }
+  return null
+}
+
+function reportCacheFailure(operation: string, error: unknown): void {
+  logger.warn('Ecommerce cache operation failed; degrading to a cache miss', { operation, err: error })
+  getTelemetryRuntime()?.reportError(error, {
+    module: 'ecommerce',
+    code: 'ecommerce.cache_operation_failed',
+    attributes: { operation },
+  })
+}
+
+type TenantScopedCacheOptions = {
+  cache: CacheStrategy | null
+  tenantId: string | null
+  baseTags: string[]
+}
+
+function createTenantScopedAccess({ cache, tenantId, baseTags }: TenantScopedCacheOptions) {
+  return {
+    async get<T>(key: string): Promise<T | null> {
+      if (!cache) return null
+      try {
+        const value = await runWithCacheTenant(tenantId, () => cache.get(key))
+        return (value ?? null) as T | null
+      } catch (error) {
+        reportCacheFailure('get', error)
+        return null
+      }
+    },
+    async set<T>(key: string, value: T, ttlMs: number, tags: string[] | undefined): Promise<void> {
+      if (!cache) return
+      const mergedTags = Array.from(new Set([...baseTags, ...(tags ?? [])]))
+      try {
+        await runWithCacheTenant(tenantId, () => cache.set(key, value, { ttl: ttlMs, tags: mergedTags }))
+      } catch (error) {
+        reportCacheFailure('set', error)
+      }
+    },
+    async deleteByTags(tags: string[]): Promise<number> {
+      if (!cache || tags.length === 0) return 0
+      try {
+        return await runWithCacheTenant(tenantId, () => cache.deleteByTags(tags))
+      } catch (error) {
+        reportCacheFailure('deleteByTags', error)
+        return 0
+      }
+    },
+  }
+}
+
+export function storefrontCache(container: CacheContainer | null | undefined, ctx: StoreContext): StorefrontCache {
+  const access = createTenantScopedAccess({
+    cache: resolveCacheService(container),
+    tenantId: ctx.tenantId,
+    baseTags: [ecommerceStoreTag(ctx.store.id)],
+  })
+  return {
+    get: (parts, options) => access.get(buildStorefrontCacheKey(ctx, parts, options)),
+    set: (parts, value, options) =>
+      access.set(buildStorefrontCacheKey(ctx, parts, { scope: options.scope }), value, options.ttlMs, options.tags),
+    deleteByTags: (tags) => access.deleteByTags(tags),
+  }
+}
+
+export function ecommerceResolutionCache(container: CacheContainer | null | undefined): EcommerceResolutionCache {
+  const access = createTenantScopedAccess({
+    cache: resolveCacheService(container),
+    tenantId: null,
+    baseTags: [],
+  })
+  return {
+    get: (parts) => access.get(buildEcommerceResolutionCacheKey(parts)),
+    set: (parts, value, options) =>
+      access.set(buildEcommerceResolutionCacheKey(parts), value, options.ttlMs, options.tags),
+    deleteByTags: (tags) => access.deleteByTags(tags),
+  }
+}
+
+export type EcommerceCacheInvalidation = { tenantId: string | null; tags: string[] }
+
+/**
+ * Event-driven invalidation (§8): evicts `tags` from the tenant-agnostic resolution cache and, when
+ * the tenant is known, from that tenant's storefront and buyer-context caches. Tags are tenant
+ * scoped by the cache layer, so each scope is cleared inside its own tenant.
+ */
+export async function invalidateEcommerceCacheTags(
+  container: CacheContainer | null | undefined,
+  invalidation: EcommerceCacheInvalidation,
+): Promise<number> {
+  const tags = Array.from(new Set(invalidation.tags.filter((tag) => tag.length > 0)))
+  if (tags.length === 0) return 0
+  const cache = resolveCacheService(container)
+  if (!cache) return 0
+  const tenantIds = invalidation.tenantId ? [null, invalidation.tenantId] : [null]
+  let deleted = 0
+  for (const tenantId of tenantIds) {
+    deleted += await createTenantScopedAccess({ cache, tenantId, baseTags: [] }).deleteByTags(tags)
+  }
+  return deleted
+}
+
+export function buyerContextCache(
+  container: CacheContainer | null | undefined,
+  scope: BuyerContextCacheScope,
+): BuyerContextCache {
+  const access = createTenantScopedAccess({
+    cache: resolveCacheService(container),
+    tenantId: scope.tenantId,
+    baseTags: [ecommerceStoreTag(scope.storeId)],
+  })
+  return {
+    get: (customerUserId) => access.get<BuyerContext>(buildBuyerContextCacheKey(scope.storeId, customerUserId)),
+    set: (buyer) =>
+      access.set(
+        buildBuyerContextCacheKey(scope.storeId, buyer.customerUserId),
+        buyer,
+        BUYER_CONTEXT_TTL_MS,
+        buyerContextTags(buyer, scope.tenantId),
+      ),
+    deleteByTags: (tags) => access.deleteByTags(tags),
+  }
+}

package/src/modules/ecommerce/lib/createConflictRecheck.ts

@@ -0,0 +1,31 @@
+import { NextResponse } from 'next/server'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+
+type ConflictRecheck = () => Promise<void>
+
+const recheckByRequest = new WeakMap<Request, ConflictRecheck>()
+
+export function registerCreateConflictRecheck(request: Request | undefined, recheck: ConflictRecheck): void {
+  if (request) recheckByRequest.set(request, recheck)
+}
+
+export function clearCreateConflictRecheck(request: Request | undefined): void {
+  if (request) recheckByRequest.delete(request)
+}
+
+export function withCreateConflictRecheck(
+  handler: (request: Request) => Promise<Response>,
+): (request: Request) => Promise<Response> {
+  return async (request: Request): Promise<Response> => {
+    const response = await handler(request)
+    const recheck = recheckByRequest.get(request)
+    recheckByRequest.delete(request)
+    if (!recheck || response.status !== 500) return response
+    try {
+      await recheck()
+    } catch (err) {
+      if (isCrudHttpError(err) && err.status === 409) return NextResponse.json(err.body, { status: 409 })
+    }
+    return response
+  }
+}