@open-mercato/core 0.6.5-develop.5337.1.534b781eac → 0.6.5

package/src/modules/entities/api/records.ts

@@ -6,6 +6,7 @@ import type { QueryEngine, QueryOptions, Where, Sort } from '@open-mercato/share
 import { normalizeExportFormat, serializeExport, defaultExportFilename, ensureColumns } from '@open-mercato/shared/lib/crud/exporters'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { resolveOrganizationScope, getSelectedOrganizationFromRequest } from '@open-mercato/core/modules/directory/utils/organizationScope'
+import { SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, isOrmBackedSystemEntityId } from '@open-mercato/shared/lib/data/engine'
 import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { setRecordCustomFields } from '../lib/helpers'
 import { CustomFieldValue } from '../data/entities'
@@ -36,24 +37,34 @@ function isDeclaredCustomEntity(entityId: string): boolean {
 
 const CUSTOM_ENTITY_RECORD_RESOURCE_KIND = 'entities.record'
 
-async function detectCustomEntity(em: any, entityId: string): Promise<boolean> {
-  if (isDeclaredCustomEntity(entityId)) return true
+type RecordsEntityKind = 'system' | 'custom' | 'unknown'
+
+// This surface manages doc-storage records, which exist for CUSTOM entities only.
+// Module-declared ids backed by a registered ORM table are system entities — their
+// records live in their own module tables/APIs, and stray doc rows for them poisoned
+// read-path classification platform-wide (#2939) — so they are rejected outright. The
+// previous fallback that classified an entity by the mere presence of
+// `custom_entities_storage` rows is gone: within the allowed set, declaration (ce.ts)
+// or an active `custom_entities` registration is authoritative.
+async function classifyRecordsEntity(em: any, entityId: string): Promise<RecordsEntityKind> {
+  if (isOrmBackedSystemEntityId(em, entityId)) return 'system'
+  if (isDeclaredCustomEntity(entityId)) return 'custom'
   try {
     const { CustomEntity } = await import('../data/entities')
-    const found = await em.findOne(CustomEntity as any, { entityId, isActive: true })
-    if (found) return true
+    // Any registration row — active or soft-deleted — proves the id is a custom
+    // entity. Records persist beyond the definition's soft delete (TC-ENTITIES-006)
+    // and must stay readable/deletable, e.g. for the restore flow and cleanup.
+    const found = await em.findOne(CustomEntity as any, { entityId })
+    if (found) return 'custom'
   } catch {}
-  try {
-    const db = em.getKysely()
-    const row = await db
-      .selectFrom('custom_entities_storage' as any)
-      .select(['entity_id' as any])
-      .where('entity_type' as any, '=', entityId)
-      .limit(1)
-      .executeTakeFirst()
-    return !!row
-  } catch {}
-  return false
+  return 'unknown'
+}
+
+function systemEntityRecordsRejection(entityId: string) {
+  return NextResponse.json(
+    { error: 'Records are available for custom entities only', code: SYSTEM_ENTITY_RECORDS_BLOCKED_CODE, entityId },
+    { status: 400 },
+  )
 }
 
 async function readCustomEntityRecordUpdatedAt(
@@ -148,13 +159,13 @@ export async function GET(req: Request) {
     const rbac = resolve('rbacService') as RbacService
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     let organizationIds: string[] | null = scope.filterIds
-    // Read/write symmetry: this endpoint writes every record to custom_entities_storage
-    // via the data engine, including module-declared custom entities whose id is a
-    // frozen system id and therefore never registered in `custom_entities`. detectCustomEntity
-    // covers the declared-entity registry plus the custom_entities / doc-storage fallbacks
-    // (mirrors HybridQueryEngine.isCustomEntity) so mapRow strips the cf_ prefix and the edit
-    // form can read back saved values.
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    // Module-declared custom entities (ce.ts) carry frozen system-style ids and are never
+    // registered in `custom_entities`, so classification checks the declared registry plus
+    // active registrations. System (table-backed) ids are rejected above; for the allowed
+    // set `isCustomEntity` drives mapRow's cf_ stripping so the edit form reads back values.
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'view', isCustomEntity, rbac })
     if (organizationIds && organizationIds.length === 0) {
       return NextResponse.json({ items: [], total: 0, page, pageSize, totalPages: 0 })
@@ -230,6 +241,10 @@ export async function GET(req: Request) {
     if (organizationIds && organizationIds.length) {
       qopts.organizationIds = organizationIds
     }
+    // Allowed entities are doc-storage-backed by definition (system ids were rejected
+    // above) — direct the engine to doc storage explicitly so reads stay deterministic
+    // even before the first record exists.
+    if (isCustomEntity) qopts.forceCustomEntityStorage = true
     for (const [k, v] of qpEntries) buildFilter(k, v, isCustomEntity)
     const res = await qe.query(entityId as any, qopts)
     const rawItems = res.items || []
@@ -363,7 +378,9 @@ export async function POST(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     const norm = normalizeValues(values)
 
@@ -427,7 +444,9 @@ export async function PUT(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     const norm = normalizeValues(values)
 
@@ -516,7 +535,9 @@ export async function DELETE(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const isCustomEntity = await detectCustomEntity(em, entityId)
+    const entityKind = await classifyRecordsEntity(em, entityId)
+    if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
+    const isCustomEntity = entityKind === 'custom'
     await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
     await de.deleteCustomEntityRecord({ entityId, recordId, organizationId: targetOrgId, tenantId: auth.tenantId!, soft: true })
     return NextResponse.json({ ok: true })

package/src/modules/entities/backend/entities/user/[entityId]/records/[recordId]/page.tsx

@@ -6,6 +6,8 @@ import { z } from 'zod'
 import { apiCall, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError, raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type UpdateRecordRequest = (payload: { entityId: string; recordId: string; values: Record<string, unknown> }) => Promise<void>
 
@@ -38,6 +40,19 @@ export async function submitCustomEntityRecordUpdate(options: {
 type RecordsResponse = { items: any[] }
 
 export default function EditRecordPage({ params }: { params: { entityId?: string; recordId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard === 'blocked') {
+    return <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+  }
+  if (guard === 'checking') {
+    return <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+  }
+  return <EditRecordPageInner params={params} />
+}
+
+function EditRecordPageInner({ params }: { params: { entityId?: string; recordId?: string } }) {
   const t = useT()
   const entityId = decodeURIComponent(params?.entityId || '')
   const recordId = decodeURIComponent(params?.recordId || '')

package/src/modules/entities/backend/entities/user/[entityId]/records/create/page.tsx

@@ -6,6 +6,8 @@ import { CrudForm, type CrudField } from '@open-mercato/ui/backend/CrudForm'
 import { z } from 'zod'
 import { createCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type CreateRecordRequest = (payload: { entityId: string; values: Record<string, unknown> }) => Promise<void>
 
@@ -30,6 +32,19 @@ export async function submitCustomEntityRecord(options: {
 }
 
 export default function CreateRecordPage({ params }: { params: { entityId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard === 'blocked') {
+    return <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+  }
+  if (guard === 'checking') {
+    return <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+  }
+  return <CreateRecordPageInner params={params} />
+}
+
+function CreateRecordPageInner({ params }: { params: { entityId?: string } }) {
   const t = useT()
   const router = useRouter()
   const entityId = decodeURIComponent(params?.entityId || '')

package/src/modules/entities/backend/entities/user/[entityId]/records/page.tsx

@@ -17,6 +17,9 @@ import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { raiseCrudError } from '@open-mercato/ui/backend/utils/serverErrors'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useRecordsEntityGuard } from '@open-mercato/core/modules/entities/components/useRecordsEntityGuard'
 
 type RecordsResponse = {
   items: any[]
@@ -44,6 +47,26 @@ function normalizeCell(v: any): string {
 }
 
 export default function RecordsPage({ params }: { params: { entityId?: string } }) {
+  const t = useT()
+  const entityId = decodeURIComponent(params?.entityId || '')
+  const guard = useRecordsEntityGuard(entityId)
+  if (guard !== 'allowed') {
+    return (
+      <Page>
+        <PageBody>
+          {guard === 'blocked' ? (
+            <ErrorMessage label={t('entities.userEntities.records.errors.systemEntity', 'This entity is system-managed. Records are available for custom entities only.')} />
+          ) : (
+            <LoadingMessage label={t('entities.userEntities.records.loading', 'Loading records...')} />
+          )}
+        </PageBody>
+      </Page>
+    )
+  }
+  return <RecordsPageInner params={params} />
+}
+
+function RecordsPageInner({ params }: { params: { entityId?: string } }) {
   const entityId = decodeURIComponent(params?.entityId || '')
   const [sorting, setSorting] = React.useState<SortingState>([{ id: 'id', desc: false }])
   const [page, setPage] = React.useState(1)

package/src/modules/entities/components/useRecordsEntityGuard.ts

@@ -0,0 +1,41 @@
+"use client"
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+
+export type RecordsEntityGuardState = 'checking' | 'blocked' | 'allowed'
+
+// Mirrors SYSTEM_ENTITY_RECORDS_BLOCKED_CODE from @open-mercato/shared/lib/data/engine —
+// kept as a literal so client bundles do not pull the server-side data engine in.
+const SYSTEM_ENTITY_RECORDS_BLOCKED_CODE = 'system_entity_records_blocked'
+
+/**
+ * The records surface serves custom entities only; the API rejects system
+ * (table-backed) entity ids with 400 + `system_entity_records_blocked` (#2939
+ * hardening). Records pages are URL-addressable for any entity id, so they probe
+ * once and render a dedicated error state instead of a broken table/form.
+ * Fails open on transport errors — the page's own data calls surface those.
+ */
+export function useRecordsEntityGuard(entityId: string): RecordsEntityGuardState {
+  const [state, setState] = React.useState<RecordsEntityGuardState>(entityId ? 'checking' : 'allowed')
+  React.useEffect(() => {
+    if (!entityId) {
+      setState('allowed')
+      return
+    }
+    let cancelled = false
+    setState('checking')
+    apiCall<{ code?: string }>(`/api/entities/records?entityId=${encodeURIComponent(entityId)}&page=1&pageSize=1`)
+      .then((res) => {
+        if (cancelled) return
+        const blocked = res.status === 400 && res.result?.code === SYSTEM_ENTITY_RECORDS_BLOCKED_CODE
+        setState(blocked ? 'blocked' : 'allowed')
+      })
+      .catch(() => {
+        if (!cancelled) setState('allowed')
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [entityId])
+  return state
+}

package/src/modules/entities/i18n/de.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Datensatz konnte nicht gelöscht werden",
   "entities.userEntities.records.errors.entityIdRequired": "Entitätskennung ist erforderlich",
   "entities.userEntities.records.errors.recordIdRequired": "Datensatzkennung ist erforderlich",
+  "entities.userEntities.records.errors.systemEntity": "Diese Entität wird vom System verwaltet. Datensätze sind nur für benutzerdefinierte Entitäten verfügbar.",
   "entities.userEntities.records.form.createTitle": "Datensatz erstellen",
   "entities.userEntities.records.form.editTitle": "Datensatz bearbeiten",
   "entities.userEntities.records.form.submitCreate": "Erstellen",

package/src/modules/entities/i18n/en.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Failed to delete record",
   "entities.userEntities.records.errors.entityIdRequired": "Entity identifier is required",
   "entities.userEntities.records.errors.recordIdRequired": "Record identifier is required",
+  "entities.userEntities.records.errors.systemEntity": "This entity is system-managed. Records are available for custom entities only.",
   "entities.userEntities.records.form.createTitle": "Create record",
   "entities.userEntities.records.form.editTitle": "Edit record",
   "entities.userEntities.records.form.submitCreate": "Create",

package/src/modules/entities/i18n/es.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "No se pudo eliminar el registro",
   "entities.userEntities.records.errors.entityIdRequired": "Se requiere el identificador de la entidad",
   "entities.userEntities.records.errors.recordIdRequired": "Se requiere el identificador del registro",
+  "entities.userEntities.records.errors.systemEntity": "Esta entidad está gestionada por el sistema. Los registros solo están disponibles para entidades personalizadas.",
   "entities.userEntities.records.form.createTitle": "Crear registro",
   "entities.userEntities.records.form.editTitle": "Editar registro",
   "entities.userEntities.records.form.submitCreate": "Crear",

package/src/modules/entities/i18n/pl.json

@@ -82,6 +82,7 @@
   "entities.userEntities.records.errors.deleteFailed": "Nie udało się usunąć rekordu",
   "entities.userEntities.records.errors.entityIdRequired": "Wymagany jest identyfikator encji",
   "entities.userEntities.records.errors.recordIdRequired": "Wymagany jest identyfikator rekordu",
+  "entities.userEntities.records.errors.systemEntity": "Ta encja jest zarządzana systemowo. Rekordy są dostępne wyłącznie dla encji niestandardowych.",
   "entities.userEntities.records.form.createTitle": "Utwórz rekord",
   "entities.userEntities.records.form.editTitle": "Edytuj rekord",
   "entities.userEntities.records.form.submitCreate": "Utwórz",

package/src/modules/payment_gateways/api/transactions/route.ts

@@ -5,16 +5,13 @@ import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { GatewayTransaction } from '../../data/entities'
 import { listTransactionsQuerySchema } from '../../data/validators'
 import { paymentGatewaysTag } from '../openapi'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
 
 export const metadata = {
   path: '/payment_gateways/transactions',
   GET: { requireAuth: true, requireFeatures: ['payment_gateways.view'] },
 }
 
-function escapeLikePattern(value: string): string {
-  return value.replace(/[\\%_]/g, '\\$&')
-}
-
 function formatDateValue(value: unknown): string | null {
   if (!value) return null
   if (value instanceof Date) return value.toISOString()
@@ -58,7 +55,7 @@ export async function GET(req: Request) {
     qb.andWhere({ unifiedStatus: status })
   }
   if (search) {
-    const pattern = `%${escapeLikePattern(search)}%`
+    const pattern = buildIlikeTerm(search)
     qb.andWhere(`(
       cast(gt.id as text) ilike ?
       or cast(gt.payment_id as text) ilike ?

package/src/modules/progress/api/jobs/[id]/route.ts

@@ -26,6 +26,7 @@ export async function GET(req: Request, { params }: { params: { id: string } })
   const job = await em.findOne(ProgressJob, {
     id: params.id,
     tenantId: auth.tenantId,
+    ...(auth.orgId ? { organizationId: auth.orgId } : {}),
   })
 
   if (!job) {
@@ -74,7 +75,11 @@ export async function PUT(req: Request, { params }: { params: { id: string } })
 
   const container = await createRequestContainer()
   const em = container.resolve('em') as EntityManager
-  const existing = await em.findOne(ProgressJob, { id: params.id, tenantId: auth.tenantId })
+  const existing = await em.findOne(ProgressJob, {
+    id: params.id,
+    tenantId: auth.tenantId,
+    ...(auth.orgId ? { organizationId: auth.orgId } : {}),
+  })
   if (!existing) {
     return NextResponse.json({ error: 'Not found' }, { status: 404 })
   }

package/src/modules/progress/api/jobs/route.ts

@@ -165,7 +165,7 @@ export async function POST(req: Request) {
     const stack = error instanceof Error ? error.stack : undefined
     console.error('[progress.jobs.create] unhandled error', { message, stack })
     return NextResponse.json(
-      { error: 'Failed to create progress job.', message, stack },
+      { error: 'Failed to create progress job.' },
       { status: 500 },
     )
   }

package/src/modules/progress/lib/progressServiceImpl.ts

@@ -75,7 +75,11 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
     },
 
     async updateProgress(jobId, input, ctx) {
-      const job = await em.findOneOrFail(ProgressJob, { id: jobId, tenantId: ctx.tenantId })
+      const job = await em.findOneOrFail(ProgressJob, {
+        id: jobId,
+        tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
+      })
       if (job.status === 'completed' || job.status === 'failed' || job.status === 'cancelled') {
         return job
       }
@@ -197,6 +201,7 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
       const job = await em.findOneOrFail(ProgressJob, {
         id: jobId,
         tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
         cancellable: true,
         status: { $in: ['pending', 'running'] },
       })
@@ -279,6 +284,7 @@ export function createProgressService(em: EntityManager, eventBus: { emit: (even
       return em.findOne(ProgressJob, {
         id: jobId,
         tenantId: ctx.tenantId,
+        ...(ctx.organizationId ? { organizationId: ctx.organizationId } : {}),
       })
     },
 

package/src/modules/query_index/data/entities.ts

@@ -254,6 +254,7 @@ export class IndexerStatusLog {
 @Entity({ tableName: 'search_tokens' })
 @Index({ name: 'search_tokens_lookup_idx', properties: ['entityType', 'field', 'tokenHash', 'tenantId', 'organizationId'] })
 @Index({ name: 'search_tokens_entity_idx', properties: ['entityType', 'entityId'] })
+@Index({ name: 'search_tokens_tenant_token_hash_idx', properties: ['tenantId', 'tokenHash'] })
 export class SearchToken {
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string

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

@@ -2,7 +2,7 @@ import type { QueryEngine, QueryOptions, QueryResult, FilterOp, Filter, QueryCus
 import { SortDir } from '@open-mercato/shared/lib/query/types'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
-import { BasicQueryEngine, resolveEntityTableName } from '@open-mercato/shared/lib/query/engine'
+import { BasicQueryEngine, resolveEntityTableName, resolveRegisteredEntityTableName } from '@open-mercato/shared/lib/query/engine'
 import { type Kysely, sql, type RawBuilder } from 'kysely'
 import type { EventBus } from '@open-mercato/events'
 import { readCoverageSnapshot, refreshCoverageSnapshot } from './coverage'
@@ -219,7 +219,7 @@ export class HybridQueryEngine implements QueryEngine {
       const debugEnabled = this.isDebugVerbosity()
       if (debugEnabled) this.debug('query:start', { entity })
 
-      const isCustom = await this.isCustomEntity(entity)
+      const isCustom = opts.forceCustomEntityStorage === true || await this.isCustomEntity(entity)
       if (isCustom) {
         if (debugEnabled) this.debug('query:custom-entity', { entity })
         const section = profiler.section('custom_entity')
@@ -1005,6 +1005,14 @@ export class HybridQueryEngine implements QueryEngine {
         .executeTakeFirst()
       if (row) {
         result = true
+      } else if (resolveRegisteredEntityTableName(this.em, entity) !== null) {
+        // An id backed by a registered ORM table is never doc-storage-backed by
+        // inference: stray `custom_entities_storage` rows for such an id (e.g. written
+        // through the generic entities data engine) must not hijack every list/detail
+        // read for the whole entity type away from its base table (#2939). Surfaces
+        // that intentionally read doc records for a dual-declared id pass
+        // `forceCustomEntityStorage` in QueryOptions instead.
+        result = false
       } else {
         // Read/write symmetry. Records written through the entities data engine
         // (`de.createCustomEntityRecord`) always land in `custom_entities_storage`,
@@ -1012,9 +1020,7 @@ export class HybridQueryEngine implements QueryEngine {
         // id — those are NEVER registered in `custom_entities` (install treats a
         // system id as non-registrable). Without this fallback the query routes to
         // the empty ORM/index path and those records are write-only (created with
-        // 200 but unreadable on the edit form). A real ORM entity never writes rows
-        // to `custom_entities_storage`, so this can only ever re-classify genuine
-        // doc-storage entities — it cannot misroute table-backed entities.
+        // 200 but unreadable on the edit form).
         result = await this.hasCustomEntityStorageRows(entity)
       }
     } catch {

package/src/modules/query_index/migrations/.snapshot-open-mercato.json

@@ -1354,6 +1354,17 @@
           "primary": false,
           "unique": false
         },
+        {
+          "columnNames": [
+            "tenant_id",
+            "token_hash"
+          ],
+          "composite": true,
+          "constraint": false,
+          "keyName": "search_tokens_tenant_token_hash_idx",
+          "primary": false,
+          "unique": false
+        },
         {
           "columnNames": [
             "id"

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

@@ -0,0 +1,29 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// #2966: TokenSearchStrategy — the always-available global-search fallback —
+// filters search_tokens by token_hash IN (...) AND tenant_id on every
+// keystroke, but both existing indexes lead with entity_type (and the lookup
+// index interposes field, which the query never filters), so the per-keystroke
+// lookup degrades to a sequential scan as the table grows. Add a
+// (tenant_id, token_hash)-leading index so it becomes an index scan.
+//
+// search_tokens is high-churn (rows scale with records × tokens), so the
+// index is built CONCURRENTLY to avoid blocking writes during the build.
+// CREATE INDEX CONCURRENTLY cannot run inside a transaction, hence
+// isTransactional() => false; the migration runner applies migrations
+// one-by-one, so this opt-out is safe.
+export class Migration20260611103000_query_index extends Migration {
+
+  override isTransactional(): boolean {
+    return false;
+  }
+
+  override up(): void | Promise<void> {
+    this.addSql(`create index concurrently if not exists "search_tokens_tenant_token_hash_idx" on "search_tokens" ("tenant_id", "token_hash");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "search_tokens_tenant_token_hash_idx";`);
+  }
+
+}

package/src/modules/resources/api/resources.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
-import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { ResourcesResource, ResourcesResourceTagAssignment, ResourcesResourceTag } from '../data/entities'
 import { resourcesResourceCreateSchema, resourcesResourceUpdateSchema } from '../data/validators'
@@ -107,8 +107,7 @@ const crud = makeCrudRoute({
       }
       const term = sanitizeSearchTerm(query.search)
       if (term) {
-        const like = `%${escapeLikePattern(term)}%`
-        filters[F.name] = { $ilike: like }
+        filters[F.name] = { $ilike: buildIlikeTerm(term) }
       }
       if (query.resourceTypeId) {
         filters[F.resource_type_id] = query.resourceTypeId

package/src/modules/sales/api/documents/factory.ts

@@ -17,7 +17,7 @@ import {
 } from '../openapi'
 import { parseScopedCommandInput, resolveCrudRecordId } from '../utils'
 import { documentUpdateSchema } from '../../commands/documents'
-import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import type { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { recalculateOrderTotalsForDisplay } from '../../commands/returns'
@@ -101,7 +101,7 @@ function buildFilters(query: ListQuery, numberColumn: string, kind: DocumentKind
   const filters: Record<string, unknown> = {}
   if (query.id) filters.id = { $eq: query.id }
   if (query.search && query.search.trim().length > 0) {
-    const term = `%${escapeLikePattern(query.search.trim())}%`
+    const term = buildIlikeTerm(query.search.trim())
     filters[numberColumn] = { $ilike: term }
   }
   if (query.customerId) {

package/src/modules/sales/commands/documents.ts

@@ -719,11 +719,13 @@ async function resolveAddressSnapshot(
   addressId?: string | null,
 ): Promise<Record<string, unknown> | null> {
   if (!addressId) return null;
-  const address = await em.findOne(CustomerAddress, {
-    id: addressId,
-    organizationId,
-    tenantId,
-  });
+  const address = await findOneWithDecryption(
+    em,
+    CustomerAddress,
+    { id: addressId, organizationId, tenantId },
+    undefined,
+    { tenantId, organizationId },
+  );
   if (!address) return null;
 
   return {

package/src/modules/sales/components/documents/SalesDocumentsTable.tsx

@@ -23,6 +23,7 @@ import {
   createDictionaryMap,
   normalizeDictionaryEntries,
 } from '@open-mercato/core/modules/dictionaries/components/dictionaryAppearance'
+import { SALES_DOCUMENT_NUMBER_COLUMN_META } from './salesDocumentsColumns'
 
 type SalesDocumentKind = 'order' | 'quote'
 
@@ -594,7 +595,7 @@ export function SalesDocumentsTable({ kind }: { kind: SalesDocumentKind }) {
           ) : null}
         </div>
       ),
-      meta: { sticky: true },
+      meta: SALES_DOCUMENT_NUMBER_COLUMN_META,
     },
     {
       accessorKey: 'customerName',

package/src/modules/sales/components/documents/salesDocumentsColumns.ts

@@ -0,0 +1,6 @@
+export const SALES_DOCUMENT_NUMBER_COLUMN_MAX_WIDTH = '220px'
+
+export const SALES_DOCUMENT_NUMBER_COLUMN_META = {
+  sticky: true,
+  maxWidth: SALES_DOCUMENT_NUMBER_COLUMN_MAX_WIDTH,
+} as const

package/src/modules/staff/AGENTS.md

@@ -2,7 +2,7 @@
 
 The `staff` module is **optional** and slated for extraction into a standalone `@open-mercato/staff` package published from the [official-modules](https://github.com/open-mercato/official-modules) repository. Core modules MUST NOT take direct dependencies on staff entities, helpers, or services — cross-module contact happens through the public surfaces listed below.
 
-See [`.ai/specs/2026-05-08-staff-decouple-from-core.md`](../../../../../.ai/specs/2026-05-08-staff-decouple-from-core.md) for the decoupling plan, and [`BACKWARD_COMPATIBILITY.md`](../../../../../BACKWARD_COMPATIBILITY.md) for the contract-surface taxonomy referenced below.
+See [`.ai/specs/implemented/2026-05-08-staff-decouple-from-core.md`](../../../../../.ai/specs/implemented/2026-05-08-staff-decouple-from-core.md) for the decoupling plan, and [`BACKWARD_COMPATIBILITY.md`](../../../../../BACKWARD_COMPATIBILITY.md) for the contract-surface taxonomy referenced below.
 
 ## MUST Rules
 

package/src/modules/staff/api/team-members.ts

@@ -225,7 +225,12 @@ const crud = makeCrudRoute({
         const { translate } = await resolveTranslations()
         return parseScopedCommandInput(staffTeamMemberUpdateSchema, raw ?? {}, ctx, translate)
       },
-      response: () => ({ ok: true }),
+      // Surface the freshly-bumped updatedAt so inline (non-CrudForm) callers can
+      // refresh their optimistic-lock token between sequential edits (#2848).
+      response: (arg: { result?: { updatedAt?: string | null } | null }) => ({
+        ok: true,
+        updatedAt: arg?.result?.updatedAt ?? null,
+      }),
     },
     delete: {
       commandId: 'staff.team-members.delete',
@@ -287,7 +292,9 @@ export const openApi = createStaffCrudOpenApi({
   },
   update: {
     schema: staffTeamMemberUpdateSchema,
-    responseSchema: defaultOkResponseSchema,
+    responseSchema: defaultOkResponseSchema.extend({
+      updatedAt: z.string().nullable().optional(),
+    }),
     description: 'Updates a team member by id.',
   },
   del: {