@open-mercato/core 0.9.1-develop.7473.1.de5b22888f → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/query_index/lib/doc-enrichers.ts

@@ -0,0 +1,306 @@
+import type { Kysely } from 'kysely'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { recordIndexerError } from '@open-mercato/shared/lib/indexers/error-log'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
+
+const logger = createLogger('query_index').child({ component: 'doc-enrichers' })
+
+/**
+ * Index-document enrichment — lets the module that owns an entity contribute computed keys to
+ * that entity's `entity_indexes.doc` at index time (Storefront Public API §3.3, decision D9).
+ *
+ * Registration is programmatic (call `registerIndexDocEnricher` from the owning module's `di.ts`);
+ * there is no auto-discovered module file for it.
+ *
+ * Key namespace: every enricher declares the exact keys it writes. A key MUST be a lowercase
+ * snake_case identifier (`^[a-z][a-z0-9_]*$`), so it can never collide with `cf:*` custom-field
+ * keys or `l10n:*` translation keys, MUST NOT be one of the reserved document keys, and MUST NOT be
+ * declared by another enricher of the same entity type. A key that turns out to be a base column
+ * of the indexed row is a collision detected at index time: the base value is kept, the
+ * contribution is discarded and the error is recorded.
+ *
+ * Failure semantics (fail closed, detectable): when an enricher throws, or returns nothing for a
+ * record, every key it declares is written as JSON `null` on the affected documents. Consumers
+ * MUST treat `null` (and an absent key) as "not indexed" — never as "empty". Indexing itself
+ * never fails because of an enricher.
+ *
+ * Enriched keys are filter/projection data: they are excluded from the `search_text` aggregate
+ * and from `search_tokens`.
+ */
+export type IndexDocEnricherContext = {
+  db: Kysely<any>
+  entityType: string
+  tenantId: string | null
+  organizationId: string | null
+}
+
+export type IndexDocEnricherRecord = {
+  recordId: string
+  doc: Readonly<Record<string, unknown>>
+}
+
+export type IndexDocEnrichment = Record<string, unknown>
+
+export type IndexDocEnricher = {
+  id: string
+  entityType: string
+  keys: readonly string[]
+  enrich: (
+    records: readonly IndexDocEnricherRecord[],
+    ctx: IndexDocEnricherContext,
+  ) => Promise<Map<string, IndexDocEnrichment>>
+}
+
+export type IndexDocEnrichmentTarget = {
+  recordId: string
+  doc: Record<string, unknown>
+  tenantId: string | null
+  organizationId: string | null
+}
+
+export const INDEX_DOC_ENRICHER_KEY_PATTERN = /^[a-z][a-z0-9_]*$/
+
+export const RESERVED_INDEX_DOC_KEYS: ReadonlySet<string> = new Set([
+  'id',
+  'tenant_id',
+  'organization_id',
+  'created_at',
+  'updated_at',
+  'deleted_at',
+  'search_text',
+])
+
+type RegisteredEnricher = IndexDocEnricher & { keys: string[] }
+
+type EnricherRegistryState = {
+  byEntityType: Map<string, RegisteredEnricher[]>
+}
+
+const GLOBAL_ENRICHER_REGISTRY_KEY = '__openMercatoQueryIndexDocEnrichers__' as const
+
+type GlobalEnricherRegistry = typeof globalThis & {
+  [GLOBAL_ENRICHER_REGISTRY_KEY]?: EnricherRegistryState
+}
+
+function getRegistryState(): EnricherRegistryState {
+  const globalRegistry = globalThis as GlobalEnricherRegistry
+  if (!globalRegistry[GLOBAL_ENRICHER_REGISTRY_KEY]) {
+    globalRegistry[GLOBAL_ENRICHER_REGISTRY_KEY] = { byEntityType: new Map() }
+  }
+  return globalRegistry[GLOBAL_ENRICHER_REGISTRY_KEY]
+}
+
+function validateEnricher(enricher: IndexDocEnricher, existing: readonly RegisteredEnricher[]): string[] {
+  if (typeof enricher.id !== 'string' || !enricher.id.trim()) {
+    throw new Error('[internal] Index doc enricher requires a non-empty id')
+  }
+  if (typeof enricher.entityType !== 'string' || !enricher.entityType.includes(':')) {
+    throw new Error(`[internal] Index doc enricher "${enricher.id}" requires an entityType in '<module>:<entity>' form`)
+  }
+  if (typeof enricher.enrich !== 'function') {
+    throw new Error(`[internal] Index doc enricher "${enricher.id}" requires an enrich function`)
+  }
+  const keys = Array.from(new Set(enricher.keys ?? []))
+  if (!keys.length) {
+    throw new Error(`[internal] Index doc enricher "${enricher.id}" must declare at least one key`)
+  }
+  for (const key of keys) {
+    if (!INDEX_DOC_ENRICHER_KEY_PATTERN.test(key)) {
+      throw new Error(`[internal] Index doc enricher "${enricher.id}" key "${key}" must match ${INDEX_DOC_ENRICHER_KEY_PATTERN}`)
+    }
+    if (RESERVED_INDEX_DOC_KEYS.has(key)) {
+      throw new Error(`[internal] Index doc enricher "${enricher.id}" key "${key}" is reserved`)
+    }
+    const owner = existing.find((entry) => entry.id !== enricher.id && entry.keys.includes(key))
+    if (owner) {
+      throw new Error(`[internal] Index doc enricher "${enricher.id}" key "${key}" is already contributed by "${owner.id}" for ${enricher.entityType}`)
+    }
+  }
+  return keys
+}
+
+/**
+ * Registers an enricher. Re-registering the same `id` for the same entity type replaces the
+ * previous registration (HMR-safe). Throws on an invalid or colliding key declaration.
+ * Returns a function that removes the registration.
+ */
+export function registerIndexDocEnricher(enricher: IndexDocEnricher): () => void {
+  const state = getRegistryState()
+  const existing = state.byEntityType.get(enricher.entityType) ?? []
+  const keys = validateEnricher(enricher, existing)
+  const registered: RegisteredEnricher = { ...enricher, keys }
+  const next = existing.filter((entry) => entry.id !== enricher.id)
+  next.push(registered)
+  state.byEntityType.set(enricher.entityType, next)
+  return () => {
+    const current = state.byEntityType.get(enricher.entityType) ?? []
+    const remaining = current.filter((entry) => entry !== registered)
+    if (remaining.length) state.byEntityType.set(enricher.entityType, remaining)
+    else state.byEntityType.delete(enricher.entityType)
+  }
+}
+
+export function getIndexDocEnrichers(entityType: string): readonly IndexDocEnricher[] {
+  return getRegistryState().byEntityType.get(entityType) ?? []
+}
+
+export function hasIndexDocEnrichers(entityType: string): boolean {
+  return (getRegistryState().byEntityType.get(entityType)?.length ?? 0) > 0
+}
+
+export function isIndexDocEnrichedKey(entityType: string | null | undefined, field: string): boolean {
+  if (!entityType) return false
+  const enrichers = getRegistryState().byEntityType.get(entityType)
+  if (!enrichers) return false
+  return enrichers.some((entry) => entry.keys.includes(field))
+}
+
+export function resetIndexDocEnrichers(): void {
+  getRegistryState().byEntityType.clear()
+}
+
+function scopeGroupKey(target: IndexDocEnrichmentTarget): string {
+  return `${target.tenantId ?? ''}|${target.organizationId ?? ''}`
+}
+
+async function reportEnricherFailure(
+  db: Kysely<any>,
+  input: {
+    enricher: RegisteredEnricher
+    entityType: string
+    tenantId: string | null
+    organizationId: string | null
+    recordId?: string
+    error: unknown
+    handler: string
+    details?: Record<string, unknown>
+  },
+): Promise<void> {
+  logger.error('Index doc enricher failed; contributed keys written as null', {
+    enricherId: input.enricher.id,
+    entityType: input.entityType,
+    tenantId: input.tenantId,
+    organizationId: input.organizationId,
+    recordId: input.recordId ?? null,
+    ...input.details,
+    err: input.error,
+  })
+  getTelemetryRuntime()?.reportError(input.error, {
+    module: 'query_index',
+    code: 'query_index.doc_enricher_failed',
+  })
+  await recordIndexerError(
+    { db },
+    {
+      source: 'query_index',
+      handler: input.handler,
+      error: input.error,
+      entityType: input.entityType,
+      recordId: input.recordId ?? null,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      payload: { enricherId: input.enricher.id, ...input.details },
+    },
+  ).catch(() => undefined)
+}
+
+const COLLISION_SAMPLE_SIZE = 10
+
+function nullOut(targets: readonly IndexDocEnrichmentTarget[], keys: readonly string[], baseKeys: Map<string, Set<string>>): void {
+  for (const target of targets) {
+    const ownKeys = baseKeys.get(target.recordId)
+    for (const key of keys) {
+      if (ownKeys?.has(key)) continue
+      target.doc[key] = null
+    }
+  }
+}
+
+/**
+ * Runs every enricher registered for `entityType` over a batch of freshly built documents and
+ * merges the contributed keys into them in place. One `enrich` call per enricher per
+ * tenant/organization scope present in the batch — never per record.
+ */
+export async function applyIndexDocEnrichers(
+  db: Kysely<any>,
+  entityType: string,
+  targets: readonly IndexDocEnrichmentTarget[],
+): Promise<void> {
+  const enrichers = getRegistryState().byEntityType.get(entityType)
+  if (!enrichers?.length || !targets.length) return
+
+  const baseKeys = new Map<string, Set<string>>()
+  for (const target of targets) baseKeys.set(target.recordId, new Set(Object.keys(target.doc)))
+
+  const groups = new Map<string, IndexDocEnrichmentTarget[]>()
+  for (const target of targets) {
+    const key = scopeGroupKey(target)
+    const bucket = groups.get(key)
+    if (bucket) bucket.push(target)
+    else groups.set(key, [target])
+  }
+
+  for (const enricher of [...enrichers]) {
+    for (const group of groups.values()) {
+      const { tenantId, organizationId } = group[0]
+      let result: Map<string, IndexDocEnrichment>
+      try {
+        const records = group.map((target) => ({ recordId: target.recordId, doc: target.doc }))
+        const returned = await enricher.enrich(records, { db, entityType, tenantId, organizationId })
+        if (!(returned instanceof Map)) {
+          throw new Error(`[internal] Index doc enricher "${enricher.id}" must return a Map keyed by record id`)
+        }
+        result = returned
+      } catch (error) {
+        nullOut(group, enricher.keys, baseKeys)
+        await reportEnricherFailure(db, {
+          enricher, entityType, tenantId, organizationId, error,
+          handler: 'query_index:doc-enricher',
+        })
+        continue
+      }
+
+      const collidingRecordIdsByKey = new Map<string, string[]>()
+      for (const target of group) {
+        const contribution = result.get(target.recordId)
+        const ownKeys = baseKeys.get(target.recordId)
+        for (const key of enricher.keys) {
+          if (ownKeys?.has(key)) {
+            const colliding = collidingRecordIdsByKey.get(key)
+            if (colliding) colliding.push(target.recordId)
+            else collidingRecordIdsByKey.set(key, [target.recordId])
+            continue
+          }
+          const value = contribution && Object.prototype.hasOwnProperty.call(contribution, key)
+            ? contribution[key]
+            : null
+          target.doc[key] = value === undefined ? null : value
+        }
+        if (contribution) {
+          const undeclared = Object.keys(contribution).filter((key) => !enricher.keys.includes(key))
+          if (undeclared.length) {
+            logger.warn('Index doc enricher returned undeclared keys; ignored', {
+              enricherId: enricher.id,
+              entityType,
+              recordId: target.recordId,
+              keys: undeclared,
+            })
+          }
+        }
+      }
+      for (const [key, recordIds] of collidingRecordIdsByKey) {
+        await reportEnricherFailure(db, {
+          enricher, entityType, tenantId, organizationId,
+          recordId: recordIds.length === 1 ? recordIds[0] : undefined,
+          error: new Error(`[internal] Index doc enricher "${enricher.id}" key "${key}" collides with a base document key of ${entityType} on ${recordIds.length} record(s)`),
+          handler: 'query_index:doc-enricher:collision',
+          details: {
+            collidingKey: key,
+            collidingRecordCount: recordIds.length,
+            sampleRecordIds: recordIds.slice(0, COLLISION_SAMPLE_SIZE),
+          },
+        })
+      }
+    }
+  }
+}

package/src/modules/query_index/lib/document.ts

@@ -3,6 +3,7 @@ import {
   resolveSearchConfig,
   type SearchConfig,
 } from '@open-mercato/shared/lib/search/config'
+import { isIndexDocEnrichedKey } from './doc-enrichers'
 
 export type IndexDocumentScope = {
   organizationId?: string | null
@@ -67,6 +68,7 @@ function collectAggregateSearchValues(
   }
 
   if (isSearchFieldBlocklisted(field, entityType, config)) return []
+  if (isIndexDocEnrichedKey(entityType, field)) return []
 
   if (typeof value === 'string') {
     const trimmed = value.trim()

package/src/modules/query_index/lib/engine.ts

@@ -4,6 +4,13 @@ import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { BasicQueryEngine, resolveEntityTableName, resolveRegisteredEntityTableName } from '@open-mercato/shared/lib/query/engine'
 import { isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
+import {
+  buildArrayColumnNoOverlapPredicate,
+  buildArrayColumnOverlapPredicate,
+  buildJsonbNoOverlapPredicate,
+  buildJsonbOverlapPredicate,
+  normalizeOverlapValues,
+} from '@open-mercato/shared/lib/query/overlap'
 import { type Kysely, sql, type RawBuilder } from 'kysely'
 import type { EventBus } from '@open-mercato/events'
 import { readCoverageSnapshot, refreshCoverageSnapshot } from './coverage'
@@ -70,7 +77,7 @@ type CustomFieldDefRow = {
 
 /** Operators `buildCfFilterExpression` compiles; anything else yields no predicate. */
 const CF_FILTER_SUPPORTED_OPS = new Set<FilterOp>([
-  'eq', 'ne', 'in', 'nin', 'like', 'ilike', 'exists', 'gt', 'gte', 'lt', 'lte',
+  'eq', 'ne', 'in', 'nin', 'like', 'ilike', 'exists', 'gt', 'gte', 'lt', 'lte', 'overlap', 'noverlap',
 ])
 
 /** Custom field kinds stored numerically (`custom_field_values.value_int`/`value_float`) — sort numerically, not as text (#5674). */
@@ -1007,6 +1014,8 @@ export class HybridQueryEngine implements QueryEngine {
           case 'like': return target.where(column, 'like', value as any)
           case 'ilike': return target.where(column, 'ilike', value as any)
           case 'exists': return value ? target.where(column, 'is not', null) : target.where(column, 'is', null)
+          case 'overlap': return target.where(buildArrayColumnOverlapPredicate(column, value))
+          case 'noverlap': return target.where(buildArrayColumnNoOverlapPredicate(column, value))
           default: return target
         }
       }
@@ -1710,6 +1719,18 @@ export class HybridQueryEngine implements QueryEngine {
           ])
         )
       }
+      case 'noverlap':
+        return sql<boolean>`false`
+      case 'overlap': {
+        const values = normalizeOverlapValues(value)
+        if (!values.length) return sql<boolean>`false`
+        return eb.or(
+          values.flatMap((val) => [
+            sql<boolean>`${textExpr} = ${val}`,
+            arrContains(val),
+          ])
+        )
+      }
       case 'nin': {
         const values = this.toArray(value)
         return sql<boolean>`${textExpr} not in (${sql.join(values.map((v) => sql`${v}`), sql`, `)})`
@@ -1886,6 +1907,18 @@ export class HybridQueryEngine implements QueryEngine {
           ])
         ))
       }
+      case 'noverlap':
+        return q.where(sql<boolean>`false`)
+      case 'overlap': {
+        const vals = normalizeOverlapValues(value)
+        if (!vals.length) return q.where(sql<boolean>`false`)
+        return q.where((eb: any) => eb.or(
+          vals.flatMap((val) => [
+            sql<boolean>`${textExpr} = ${val}`,
+            arrContains(val),
+          ])
+        ))
+      }
       case 'nin': {
         const vals = this.toArray(value)
         return q.where(sql<boolean>`${textExpr} not in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`)
@@ -1954,6 +1987,10 @@ export class HybridQueryEngine implements QueryEngine {
         const vals = this.toArray(value)
         return q.where(sql<boolean>`${textExpr} in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`)
       }
+      case 'overlap':
+        return q.where(buildJsonbOverlapPredicate(`${alias}.doc`, key, value))
+      case 'noverlap':
+        return q.where(buildJsonbNoOverlapPredicate(`${alias}.doc`, key, value))
       case 'nin': {
         const vals = this.toArray(value)
         return q.where(sql<boolean>`${textExpr} not in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`)
@@ -2071,6 +2108,8 @@ export class HybridQueryEngine implements QueryEngine {
       case 'like': return eb(column, 'like', value)
       case 'ilike': return eb(column, 'ilike', value)
       case 'exists': return eb(column, value ? 'is not' : 'is', null)
+      case 'overlap': return buildArrayColumnOverlapPredicate(column, value)
+      case 'noverlap': return buildArrayColumnNoOverlapPredicate(column, value)
       default: return sql<boolean>`true`
     }
   }
@@ -2102,6 +2141,10 @@ export class HybridQueryEngine implements QueryEngine {
         const vals = this.toArray(value)
         return sql<boolean>`${textExpr} in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`
       }
+      case 'overlap':
+        return buildJsonbOverlapPredicate(`${alias}.doc`, key, value)
+      case 'noverlap':
+        return buildJsonbNoOverlapPredicate(`${alias}.doc`, key, value)
       case 'nin': {
         const vals = this.toArray(value)
         return sql<boolean>`${textExpr} not in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`
@@ -2158,6 +2201,14 @@ export class HybridQueryEngine implements QueryEngine {
           })
           continue
         }
+        if (filter.op === 'overlap') {
+          next = next.where(buildJsonbOverlapPredicate(`${alias}.doc`, String(filter.field), filter.value))
+          continue
+        }
+        if (filter.op === 'noverlap') {
+          next = next.where(buildJsonbNoOverlapPredicate(`${alias}.doc`, String(filter.field), filter.value))
+          continue
+        }
         // Unknown field → filter on doc JSON text
         const docExpr = sql<string | null>`(${sql.ref(alias + '.doc')} ->> ${String(filter.field)})`
         next = this.applyColumnFilter(next, docExpr, filter, {
@@ -2748,6 +2799,8 @@ export class HybridQueryEngine implements QueryEngine {
             case '$like': add(field, 'like', opVal); break
             case '$ilike': add(field, 'ilike', opVal); break
             case '$exists': add(field, 'exists', opVal); break
+            case '$overlap': add(field, 'overlap', opVal); break
+            case '$noverlap': add(field, 'noverlap', opVal); break
           }
         }
       } else {
@@ -2889,6 +2942,10 @@ export class HybridQueryEngine implements QueryEngine {
         return q.where(col, 'ilike', filter.value as any)
       case 'exists':
         return filter.value ? q.where(col, 'is not', null) : q.where(col, 'is', null)
+      case 'overlap':
+        return q.where(buildArrayColumnOverlapPredicate(col, filter.value))
+      case 'noverlap':
+        return q.where(buildArrayColumnNoOverlapPredicate(col, filter.value))
       default:
         return q
     }

package/src/modules/query_index/lib/indexer.ts

@@ -13,6 +13,7 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 import { resolveSearchConfig } from '@open-mercato/shared/lib/search/config'
 import { replaceSearchTokensForRecord, deleteSearchTokensForRecord } from './search-tokens'
 import { attachAggregateSearchField, rebuildAggregateSearchField } from './document'
+import { applyIndexDocEnrichers } from './doc-enrichers'
 
 const logger = createLogger('query_index').child({ component: 'indexer' })
 
@@ -198,6 +199,13 @@ export async function buildIndexDoc(em: EntityManager, params: BuildDocParams):
     }
   } catch {}
 
+  await applyIndexDocEnrichers(db, params.entityType, [{
+    recordId: String(params.recordId),
+    doc,
+    tenantId: params.tenantId ?? null,
+    organizationId: params.organizationId ?? null,
+  }])
+
   // Kept outside the guard below: a failure while building the aggregate search field is a
   // bug in the aggregation or its configuration, and must surface instead of being mistaken
   // for an encryption failure and silently skipping encryption.

package/src/modules/query_index/lib/search-tokens.ts

@@ -10,6 +10,7 @@ import { looksLikeEncryptedPayload } from '@open-mercato/shared/lib/encryption/a
 import { createKmsService, resolveEncryptionMode, type KmsService } from '@open-mercato/shared/lib/encryption/kms'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { isIndexDocEnrichedKey } from './doc-enrichers'
 
 const logger = createLogger('query_index').child({ component: 'search-tokens' })
 
@@ -166,6 +167,7 @@ function shouldIndexField(
   if (lower.endsWith('_at')) return false
   if (['created_at', 'updated_at', 'deleted_at', 'tenant_id', 'organization_id'].includes(lower)) return false
   if (isSearchFieldBlocklisted(field, entityType, config)) return false
+  if (isIndexDocEnrichedKey(entityType, field)) return false
   return collectTextValues(value).some((text) => text.length > 0)
 }
 

package/src/modules/query_index/migrations/Migration20261005201500_query_index.ts

@@ -0,0 +1,42 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// GIN expression index serving the storefront assortment predicate (Storefront Public API
+// §3.3, D9): `(doc -> 'scope_keys') ?| $n::text[]` on catalog:catalog_product index documents,
+// whose `scope_keys` key the catalog contributes through its doc enricher
+// (catalog/lib/productScopeKeys.ts).
+//
+// Ownership: query_index owns the migration (as the spec's §3.3 table assigns it) because it
+// owns `entity_indexes`; a catalog migration cannot do it, since modules migrate in
+// alphabetical order and on a fresh database catalog's migrations run before query_index
+// creates the table. MANUAL DDL: a partial expression index keyed on another module's entity
+// type is not modelled on the EntityIndexRow entity, so `.snapshot-open-mercato.json` does not
+// record it; `yarn db:generate` diffs entity metadata against the snapshot, so it never emits a
+// drop for it (same approach as the Omnibus trigger DDL in catalog's
+// Migration20261005150824_catalog).
+//
+// The expression must be spelled exactly as the query engine emits it
+// (`jsonbDocKeyExpression` in @open-mercato/shared/lib/query/overlap emits the key as a
+// literal) or PostgreSQL silently falls back to a sequential scan; the catalog
+// product-scope-keys-index test pins both sides. Default `jsonb_ops` (not `jsonb_path_ops`),
+// because only `jsonb_ops` supports `?|`.
+//
+// entity_indexes is high-churn, so the index is built CONCURRENTLY, which cannot run inside a
+// transaction (isTransactional() => false; the runner applies migrations one-by-one). Drop
+// first so retrying an interrupted build removes PostgreSQL's INVALID index stub. Same shape as
+// Migration20260731105052_query_index.
+export class Migration20261005201500_query_index extends Migration {
+
+  override isTransactional(): boolean {
+    return false;
+  }
+
+  override up(): void | Promise<void> {
+    this.addSql(`drop index concurrently if exists "entity_indexes_catalog_product_scope_keys_gin_idx";`);
+    this.addSql(`create index concurrently "entity_indexes_catalog_product_scope_keys_gin_idx" on "entity_indexes" using gin (("doc" -> 'scope_keys')) where "entity_type" = 'catalog:catalog_product';`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index concurrently if exists "entity_indexes_catalog_product_scope_keys_gin_idx";`);
+  }
+
+}

package/src/modules/translations/components/TranslationManager.tsx

@@ -190,8 +190,8 @@ export function TranslationManager({
   })
 
   const fieldList = React.useMemo(
-    () => resolveFieldList(entityType, propTranslatableFields, fieldDefs as Array<{ key: string; kind: string; label?: string }>),
-    [entityType, propTranslatableFields, fieldDefs],
+    () => resolveFieldList(entityType, propTranslatableFields, fieldDefs as Array<{ key: string; kind: string; label?: string }>, baseValues),
+    [entityType, propTranslatableFields, fieldDefs, baseValues],
   )
 
   const {
@@ -440,7 +440,7 @@ export function TranslationManager({
           </thead>
           <tbody>
             {fieldList.map((field) => {
-              const baseVal = getBaseValue(field.key)
+              const baseVal = field.baseValue ?? getBaseValue(field.key)
               const translatedVal = localeTranslations[field.key] ?? ''
 
               return (

package/src/modules/translations/data/validators.ts

@@ -4,7 +4,7 @@ export const translationBodySchema = z
   .record(
     z.string().trim().min(2).max(10),
     z.record(
-      z.string().trim().min(1).max(100),
+      z.string().trim().min(1).max(400),
       z.union([z.string().max(10000), z.null()]),
     ),
   )

package/src/modules/translations/lib/batch.ts

@@ -23,3 +23,50 @@ export async function batchLoadTranslations(
   }
   return map
 }
+
+type EntityTranslationsTable = {
+  entity_translations: {
+    entity_type: string
+    entity_id: string
+    translations: Record<string, Record<string, unknown>> | null
+    tenant_id: string | null
+    organization_id: string | null
+  }
+}
+
+/**
+ * Multi-entity-type variant of `batchLoadTranslations`: every request is answered by one query,
+ * keyed by entity type and then entity id. Organization matching is exact, as in the single-type helper.
+ */
+export async function batchLoadTranslationsMany(
+  db: Kysely<EntityTranslationsTable>,
+  requests: Array<{ entityType: string; entityIds: string[] }>,
+  scope: { tenantId?: string | null; organizationId?: string | null },
+): Promise<Map<string, Map<string, Record<string, Record<string, unknown>>>>> {
+  const result = new Map<string, Map<string, Record<string, Record<string, unknown>>>>()
+  const wanted = new Map<string, Set<string>>()
+  for (const request of requests) {
+    if (!result.has(request.entityType)) result.set(request.entityType, new Map())
+    const ids = wanted.get(request.entityType) ?? new Set<string>()
+    for (const id of request.entityIds) ids.add(id)
+    wanted.set(request.entityType, ids)
+  }
+  const entityTypes = Array.from(wanted.entries()).filter(([, ids]) => ids.size > 0).map(([entityType]) => entityType)
+  if (!entityTypes.length) return result
+  const entityIds = Array.from(new Set(entityTypes.flatMap((entityType) => Array.from(wanted.get(entityType) ?? []))))
+
+  const rows = await db
+    .selectFrom('entity_translations')
+    .select(['entity_type', 'entity_id', 'translations'])
+    .where('entity_type', 'in', entityTypes)
+    .where('entity_id', 'in', entityIds)
+    .where(sql<boolean>`tenant_id is not distinct from ${scope.tenantId ?? null}`)
+    .where(sql<boolean>`organization_id is not distinct from ${scope.organizationId ?? null}`)
+    .execute()
+
+  for (const row of rows) {
+    if (!wanted.get(row.entity_type)?.has(row.entity_id)) continue
+    result.get(row.entity_type)?.set(row.entity_id, row.translations ?? {})
+  }
+  return result
+}

package/src/modules/translations/lib/helpers.ts

@@ -1,3 +1,5 @@
+import { getTranslatableEntityListPath } from '@open-mercato/shared/lib/localization/translatable-fields'
+
 export function formatFieldLabel(field: string): string {
   if (field.includes('.')) {
     const parts = field.split('.')
@@ -45,6 +47,8 @@ function pluralize(word: string): string {
 export function buildEntityListUrl(entityType: string): string | null {
   const [module, entity] = entityType.split(':')
   if (!module || !entity) return null
+  const registeredPath = getTranslatableEntityListPath(entityType)
+  if (registeredPath) return registeredPath
   const prefix = `${module}_`
   const base = entity.startsWith(prefix) ? entity.slice(prefix.length) : entity
   const resource = pluralize(base).replace(/_/g, '-')

package/src/modules/translations/lib/resolve-field-list.ts

@@ -1,9 +1,9 @@
-import { getTranslatableFields } from '@open-mercato/shared/lib/localization/translatable-fields'
+import { getTranslatableFieldExpander, getTranslatableFields } from '@open-mercato/shared/lib/localization/translatable-fields'
 import { getEntityFields } from '#generated/entity-fields-registry'
 import { isTranslatableField } from './translatable-fields'
 import { formatFieldLabel } from './helpers'
 
-export type ResolvedField = { key: string; label: string; multiline: boolean }
+export type ResolvedField = { key: string; label: string; multiline: boolean; baseValue?: string }
 
 function isMultiline(key: string): boolean {
   return key === 'description' || key.includes('description') || key.includes('content')
@@ -13,6 +13,7 @@ export function resolveFieldList(
   entityType: string,
   explicitFields: string[] | undefined,
   customFieldDefs: Array<{ key: string; kind: string; label?: string }>,
+  baseValues?: Record<string, unknown> | null,
 ): ResolvedField[] {
   if (explicitFields?.length) {
     return explicitFields.map((key) => ({
@@ -56,6 +57,19 @@ export function resolveFieldList(
     }
   }
 
+  const expander = getTranslatableFieldExpander(entityType)
+  if (expander && baseValues) {
+    for (const expansion of expander(baseValues)) {
+      if (fields.some((f) => f.key === expansion.key)) continue
+      fields.push({
+        key: expansion.key,
+        label: expansion.label ?? formatFieldLabel(expansion.key),
+        multiline: isMultiline(expansion.key),
+        ...(expansion.baseValue !== undefined ? { baseValue: expansion.baseValue } : {}),
+      })
+    }
+  }
+
   if (hasExplicitList) return fields
 
   for (const def of customFieldDefs) {