@open-mercato/shared 0.8.1-develop.7274.1.21a0083828 → 0.8.1-develop.7294.1.0ef99fc518

package/src/lib/crud/factory.ts

@@ -10,6 +10,7 @@ import { resolveOrganizationScopeForRequest, type OrganizationScope } from '@ope
 import { serializeOperationMetadata } from '@open-mercato/shared/lib/commands/operationMetadata'
 import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import {
   runMutationGuards,
   bridgeLegacyGuard,
@@ -41,7 +42,7 @@ import {
   type ResolvedCustomFieldDefinitions,
 } from './custom-field-definition-index'
 import { serializeExport, normalizeExportFormat, defaultExportFilename, ensureColumns, type CrudExportFormat, type PreparedExport } from './exporters'
-import { CrudHttpError, isCrudHttpError } from './errors'
+import { CrudHttpError, isCrudHttpError, translateCrudErrorBody } from './errors'
 import type { CommandBus, CommandLogMetadata } from '@open-mercato/shared/lib/commands'
 import type { EntityId } from '@open-mercato/shared/modules/entities'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -634,9 +635,12 @@ function classifyCrudError(err: unknown): { code: CrudErrorCode; pgSqlState: str
   return { code: 'INTERNAL_ERROR', pgSqlState: null }
 }
 
-function handleError(err: unknown, request?: Request): Response {
+async function handleError(err: unknown, request?: Request): Promise<Response> {
   if (err instanceof Response) return err
-  if (isCrudHttpError(err)) return json(err.body, { status: err.status })
+  if (isCrudHttpError(err)) {
+    const { translate } = await resolveTranslations()
+    return json(translateCrudErrorBody(err.body, translate), { status: err.status })
+  }
   // A command interceptor that blocked with an explicit status is a deliberate business
   // rejection, not a server fault — surface its status and message instead of a generic 500.
   // Without a usable status the error falls through to the historical handling below (issue #5045).
@@ -2027,15 +2031,25 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
               nextPage += 1
             }
           }
+          const exportPayload = { items: exportItems, total, page: 1, pageSize: exportItems.length, totalPages: 1, ...(res.meta ? { meta: res.meta } : {}) }
+          // Serialize only after `afterList` has run: the hook is the documented place to
+          // patch values the base query cannot compute, and an export built before it runs
+          // ships a different shape than the JSON list response for the same request (#5969).
+          await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
+          profiler.mark('after_list_hook')
+          const hookExportItems = Array.isArray(exportPayload.items) ? exportPayload.items : exportItems
+          // Re-normalize after the hook: `afterList` can add keys the full-export contract
+          // strips (`_`-prefixed metadata, `cf_*`) or fail to flatten (#6019 review).
+          // Idempotent on records already shaped by normalizeFullRecordForExport above.
+          const finalExportItems = exportFullRequested
+            ? hookExportItems.map(normalizeFullRecordForExport)
+            : hookExportItems
           const prepared = exportFullRequested
-            ? { columns: ensureColumns(exportItems), rows: exportItems }
-            : prepareExportData(exportItems, opts.list, validated as any, ctx)
+            ? { columns: ensureColumns(finalExportItems), rows: finalExportItems }
+            : prepareExportData(finalExportItems, opts.list, validated as any, ctx)
           const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
           const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
           const serialized = serializeExport(prepared, requestedExport)
-          const exportPayload = { items: exportItems, total, page: 1, pageSize: exportItems.length, totalPages: 1, ...(res.meta ? { meta: res.meta } : {}) }
-          await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
-          profiler.mark('after_list_hook')
           const response = new Response(serialized.body, {
             headers: {
               'content-type': serialized.contentType,
@@ -2058,7 +2072,7 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
           finishProfile({
             result: 'export',
             cacheStatus,
-            itemCount: exportItems.length,
+            itemCount: finalExportItems.length,
             total,
           })
           return response
@@ -2230,14 +2244,22 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
       profiler.mark('access_logged', accessLogResult)
       if (exportRequested && requestedExport) {
         const exportItems = exportFullRequested ? list.map(normalizeFullRecordForExport) : list
+        const exportPayload = { items: exportItems, total: exportItems.length, page: 1, pageSize: exportItems.length, totalPages: 1 }
+        // Same ordering contract as the query-engine export path above (#5969).
+        await opts.hooks?.afterList?.(exportPayload, { ...ctx, query: validated as any })
+        profiler.mark('after_list_hook')
+        const hookExportItems = Array.isArray(exportPayload.items) ? exportPayload.items : exportItems
+        // Re-normalize after the hook: same full-export contract as the query-engine path
+        // above (#6019 review).
+        const finalExportItems = exportFullRequested
+          ? hookExportItems.map(normalizeFullRecordForExport)
+          : hookExportItems
         const prepared = exportFullRequested
-          ? { columns: ensureColumns(exportItems), rows: exportItems }
-          : prepareExportData(exportItems, opts.list, validated as any, ctx)
+          ? { columns: ensureColumns(finalExportItems), rows: finalExportItems }
+          : prepareExportData(finalExportItems, opts.list, validated as any, ctx)
         const fallbackBase = `${opts.events?.entity || resourceKind || 'list'}${exportFullRequested ? '_full' : ''}`
         const filename = finalizeExportFilename(opts.list, requestedExport, fallbackBase)
         const serialized = serializeExport(prepared, requestedExport)
-        await opts.hooks?.afterList?.({ items: exportItems, total: exportItems.length, page: 1, pageSize: exportItems.length, totalPages: 1 }, { ...ctx, query: validated as any })
-        profiler.mark('after_list_hook')
         const response = new Response(serialized.body, {
           headers: {
             'content-type': serialized.contentType,
@@ -2247,8 +2269,8 @@ export function makeCrudRoute<TCreate = any, TUpdate = any, TList = any>(opts: C
         finishProfile({
           result: 'export',
           cacheStatus,
-          itemCount: exportItems.length,
-          total: exportItems.length,
+          itemCount: finalExportItems.length,
+          total: finalExportItems.length,
           branch: 'fallback',
         })
         return response

package/src/lib/custom-fields/__tests__/kinds.test.ts

@@ -0,0 +1,208 @@
+import {
+  buildCustomFieldKindIndex,
+  createCustomFieldKindMapResolver,
+  emptyCustomFieldKindIndex,
+  mergeCustomFieldKindIndexes,
+  resolveCustomFieldKind,
+  selectCustomFieldKindMap,
+} from '../kinds'
+
+const ORG_A = '11111111-1111-4111-8111-111111111111'
+const ORG_B = '22222222-2222-4222-8222-222222222222'
+const TENANT = '33333333-3333-4333-8333-333333333333'
+
+const kindMap = (rows: Parameters<typeof buildCustomFieldKindIndex>[0], orgId: string | null = null, tenantId: string | null = null) =>
+  selectCustomFieldKindMap(buildCustomFieldKindIndex(rows), orgId, tenantId)
+
+describe('custom-fields/kinds', () => {
+  it('indexes a definition under both its authored key and its sanitized alias', () => {
+    expect(kindMap([{ key: 'order-ref', kind: 'text' }])).toEqual({ 'order-ref': 'text', order_ref: 'text' })
+  })
+
+  it('lets an authored key win over an alias another definition sanitizes to', () => {
+    const aliasFirst = kindMap([
+      { key: 'order-ref', kind: 'text' },
+      { key: 'order_ref', kind: 'integer' },
+    ])
+    const authoredFirst = kindMap([
+      { key: 'order_ref', kind: 'integer' },
+      { key: 'order-ref', kind: 'text' },
+    ])
+
+    expect(aliasFirst.order_ref).toBe('integer')
+    expect(authoredFirst.order_ref).toBe('integer')
+  })
+
+  it('normalizes rows with blank, non-string, or missing values', () => {
+    const map = kindMap([
+      { key: '  padded  ', kind: 'text' },
+      { key: 'no-kind' },
+      { key: 'null-kind', kind: null },
+      { key: 'numeric-kind', kind: 7 },
+      { key: '   ' },
+      { key: null },
+      { key: 123, kind: 'text' },
+    ])
+
+    expect(map.padded).toBe('text')
+    expect(map['no-kind']).toBeNull()
+    expect(map['null-kind']).toBeNull()
+    expect(map['numeric-kind']).toBeNull()
+    expect(map['123']).toBe('text')
+    expect(Object.keys(map)).not.toContain('')
+  })
+
+  describe('scope resolution', () => {
+    // custom_field_defs has no unique constraint on (entity_id, key): an organization may
+    // override an inherited definition, and POST /definitions does not force the override's
+    // kind to match. Typing a value by the wrong scope's definition would turn an integer
+    // custom field into a string on read — the exact regression #5968 set out to avoid.
+    const collidingDefs = [
+      { key: 'code', kind: 'integer', organizationId: ORG_A, tenantId: TENANT },
+      { key: 'code', kind: 'text', organizationId: ORG_B, tenantId: TENANT },
+      { key: 'code', kind: 'boolean', organizationId: null, tenantId: null },
+    ]
+
+    it('types a key by the definition of the row\'s own organization', () => {
+      expect(kindMap(collidingDefs, ORG_A, TENANT).code).toBe('integer')
+      expect(kindMap(collidingDefs, ORG_B, TENANT).code).toBe('text')
+    })
+
+    it('is not decided by the order rows came back in', () => {
+      const reversed = collidingDefs.slice().reverse()
+
+      expect(kindMap(reversed, ORG_A, TENANT).code).toBe('integer')
+      expect(kindMap(reversed, ORG_B, TENANT).code).toBe('text')
+    })
+
+    it('prefers a tenant-scoped definition over a global one when no organization matches', () => {
+      const defs = [
+        { key: 'code', kind: 'boolean', organizationId: null, tenantId: null },
+        { key: 'code', kind: 'float', organizationId: null, tenantId: TENANT },
+      ]
+
+      expect(kindMap(defs, null, TENANT).code).toBe('float')
+    })
+
+    it('falls back to the global definition for an organization that defines none', () => {
+      const unknownOrg = '44444444-4444-4444-8444-444444444444'
+
+      expect(kindMap(collidingDefs, unknownOrg, TENANT).code).toBe('boolean')
+    })
+
+    it('breaks a same-scope tie deterministically rather than by row order', () => {
+      const defs = [
+        { key: 'code', kind: 'integer', organizationId: ORG_A, tenantId: TENANT, configJson: { priority: 5 } },
+        { key: 'code', kind: 'text', organizationId: ORG_A, tenantId: TENANT, configJson: { priority: 1 } },
+      ]
+
+      expect(kindMap(defs, ORG_A, TENANT).code).toBe('text')
+      expect(kindMap(defs.slice().reverse(), ORG_A, TENANT).code).toBe('text')
+    })
+
+    it('applies the same scope rule to a sanitized alias as to an authored key', () => {
+      const defs = [
+        { key: 'order-ref', kind: 'integer', organizationId: ORG_A, tenantId: TENANT },
+        { key: 'order-ref', kind: 'text', organizationId: ORG_B, tenantId: TENANT },
+      ]
+
+      expect(kindMap(defs, ORG_A, TENANT).order_ref).toBe('integer')
+      expect(kindMap(defs, ORG_B, TENANT).order_ref).toBe('text')
+    })
+  })
+
+  describe('createCustomFieldKindMapResolver', () => {
+    const index = buildCustomFieldKindIndex([
+      { key: 'code', kind: 'integer', organizationId: ORG_A, tenantId: TENANT },
+      { key: 'code', kind: 'text', organizationId: ORG_B, tenantId: TENANT },
+    ])
+
+    it('gives each organization its own map', () => {
+      const resolve = createCustomFieldKindMapResolver(index)
+
+      expect(resolve(ORG_A, TENANT).code).toBe('integer')
+      expect(resolve(ORG_B, TENANT).code).toBe('text')
+    })
+
+    it('reuses the map for a repeated scope', () => {
+      const resolve = createCustomFieldKindMapResolver(index)
+
+      expect(resolve(ORG_A, TENANT)).toBe(resolve(ORG_A, TENANT))
+      expect(resolve(ORG_A, TENANT)).not.toBe(resolve(ORG_B, TENANT))
+    })
+
+    it('yields an empty map for an absent index', () => {
+      expect(createCustomFieldKindMapResolver(null)(ORG_A, TENANT)).toEqual({})
+    })
+  })
+
+  describe('mergeCustomFieldKindIndexes', () => {
+    it('lets the earliest source win when several define the same key', () => {
+      // The query engine reads a cf value with `coalesce(source0, source1, ...)`, so the kind
+      // has to come from the same source the value did.
+      const base = buildCustomFieldKindIndex([{ key: 'code', kind: 'text' }])
+      const joined = buildCustomFieldKindIndex([
+        { key: 'code', kind: 'integer' },
+        { key: 'extra', kind: 'boolean' },
+      ])
+
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([base, joined]), null, null))
+        .toEqual({ code: 'text', extra: 'boolean' })
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([joined, base]), null, null))
+        .toEqual({ code: 'integer', extra: 'boolean' })
+    })
+
+    it('keeps the earlier source winning per scope, not just for the default one', () => {
+      const base = buildCustomFieldKindIndex([
+        { key: 'code', kind: 'text', organizationId: ORG_A, tenantId: TENANT },
+      ])
+      const joined = buildCustomFieldKindIndex([
+        { key: 'code', kind: 'integer', organizationId: ORG_A, tenantId: TENANT },
+      ])
+
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([base, joined]), ORG_A, TENANT).code).toBe('text')
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([joined, base]), ORG_A, TENANT).code).toBe('integer')
+    })
+
+    it('ignores absent sources when merging', () => {
+      const index = buildCustomFieldKindIndex([{ key: 'code', kind: 'text' }])
+
+      expect(selectCustomFieldKindMap(
+        mergeCustomFieldKindIndexes([null, index, undefined, emptyCustomFieldKindIndex()]), null, null,
+      )).toEqual({ code: 'text' })
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([]), null, null)).toEqual({})
+    })
+
+    it('keeps a null kind from an earlier source instead of falling through', () => {
+      const base = buildCustomFieldKindIndex([{ key: 'code' }])
+      const joined = buildCustomFieldKindIndex([{ key: 'code', kind: 'integer' }])
+
+      expect(selectCustomFieldKindMap(mergeCustomFieldKindIndexes([base, joined]), null, null).code).toBeNull()
+    })
+  })
+
+  describe('resolveCustomFieldKind', () => {
+    it('resolves both index-document key shapes', () => {
+      const map = kindMap([{ key: 'note', kind: 'multiline' }])
+
+      expect(resolveCustomFieldKind(map, 'cf:note')).toBe('multiline')
+      expect(resolveCustomFieldKind(map, 'cf_note')).toBe('multiline')
+    })
+
+    it('resolves a sanitized document key back to its authored definition', () => {
+      const map = kindMap([{ key: 'order-ref', kind: 'text' }])
+
+      expect(resolveCustomFieldKind(map, 'cf_order_ref')).toBe('text')
+      expect(resolveCustomFieldKind(map, 'cf:order-ref')).toBe('text')
+    })
+
+    it('returns null for an unknown key, an absent map, or a bare prefix', () => {
+      const map = kindMap([{ key: 'note', kind: 'text' }])
+
+      expect(resolveCustomFieldKind(map, 'cf:missing')).toBeNull()
+      expect(resolveCustomFieldKind(null, 'cf:note')).toBeNull()
+      expect(resolveCustomFieldKind(undefined, 'cf:note')).toBeNull()
+      expect(resolveCustomFieldKind(map, 'cf:')).toBeNull()
+    })
+  })
+})

package/src/lib/custom-fields/kinds.ts

@@ -0,0 +1,205 @@
+/**
+ * Custom-field `kind` lookup for the `cf:`/`cf_` keys carried by a query-index document.
+ *
+ * `decryptCustomFieldValue` cannot recover a value's original JS type from the ciphertext
+ * alone: the encrypt path stores a raw string unwrapped and JSON-stringifies everything
+ * else, so the string `"123"` and the number `123` produce the same plaintext. The field's
+ * `kind` is the only disambiguator, which is why every index-document read path has to
+ * resolve it before decrypting (issue #5968).
+ *
+ * `custom_field_defs` has no unique constraint on `(entity_id, key)` — per-scope overrides
+ * are a first-class feature, and an organization's override may declare a different `kind`
+ * than the tenant-wide or global definition it shadows. A flat "last row wins" map would
+ * therefore type a value from whichever definition the database happened to return last.
+ * So the index keeps every candidate definition per key and resolves the winner against the
+ * scope of the row being decrypted, through the same `selectDefinitionForRecord` precedence
+ * the non-indexed loader in `crud/custom-fields.ts` already applies per record.
+ */
+import {
+  selectDefinitionForRecord,
+  sortDefinitionSummaries,
+  summarizeDefinitionRow,
+  type CustomFieldDefinitionSummary,
+} from '../crud/custom-field-definition-index'
+
+export type CustomFieldKindMap = Record<string, string | null>
+
+export type CustomFieldKindRow = {
+  key: unknown
+  kind?: unknown
+  organizationId?: unknown
+  tenantId?: unknown
+  configJson?: unknown
+  updatedAt?: unknown
+}
+
+/**
+ * Candidate definitions per document key. `keys` holds the authored keys; `aliases` holds
+ * the SQL-safe aliases only, and is consulted solely when the document key matches no
+ * authored key — so a literal `my_field` definition is never shadowed by the alias a
+ * `my-field` definition also sanitizes to.
+ */
+export type CustomFieldKindIndex = {
+  keys: Map<string, CustomFieldDefinitionSummary[]>
+  aliases: Map<string, CustomFieldDefinitionSummary[]>
+}
+
+/** Resolves the kind map that applies to a row in the given scope. */
+export type CustomFieldKindMapResolver = (
+  organizationId: string | null | undefined,
+  tenantId: string | null | undefined,
+) => CustomFieldKindMap
+
+const CF_KEY_PREFIX = /^cf[:_]/
+
+/**
+ * Mirrors `HybridQueryEngine.sanitize()`, which aliases the doc key `cf:my-field` as the
+ * SQL-safe column alias `cf_my_field`. The transform is lossy, so an index keyed only by the
+ * authored key would never match a sanitized alias.
+ */
+function sanitizeKey(key: string): string {
+  return key.replace(/[^a-zA-Z0-9_]/g, '_')
+}
+
+function normalizeKey(value: unknown): string {
+  if (typeof value === 'string') return value.trim()
+  if (value == null) return ''
+  return String(value).trim()
+}
+
+function normalizeScopeId(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : null
+}
+
+function normalizeTimestamp(value: unknown): Date | string | number | null {
+  if (value instanceof Date) return value
+  if (typeof value === 'string' || typeof value === 'number') return value
+  return null
+}
+
+function pushCandidate(
+  bucket: Map<string, CustomFieldDefinitionSummary[]>,
+  key: string,
+  summary: CustomFieldDefinitionSummary,
+): void {
+  const existing = bucket.get(key)
+  if (existing) existing.push(summary)
+  else bucket.set(key, [summary])
+}
+
+export function buildCustomFieldKindIndex(rows: Iterable<CustomFieldKindRow>): CustomFieldKindIndex {
+  const keys = new Map<string, CustomFieldDefinitionSummary[]>()
+  const aliases = new Map<string, CustomFieldDefinitionSummary[]>()
+  for (const row of rows) {
+    const key = normalizeKey(row.key)
+    if (!key) continue
+    const summary = summarizeDefinitionRow({
+      key,
+      entityId: '',
+      kind: typeof row.kind === 'string' && row.kind.length ? row.kind : null,
+      configJson: row.configJson ?? null,
+      organizationId: normalizeScopeId(row.organizationId),
+      tenantId: normalizeScopeId(row.tenantId),
+      deletedAt: null,
+      updatedAt: normalizeTimestamp(row.updatedAt),
+    })
+    if (!summary) continue
+    pushCandidate(keys, key, summary)
+    const alias = sanitizeKey(key)
+    if (alias !== key) pushCandidate(aliases, alias, summary)
+  }
+  // One precedence rule everywhere: `selectDefinitionForRecord` picks the scope winner and
+  // `sortDefinitionSummaries` breaks ties deterministically, for authored keys and aliases
+  // alike, so no bucket depends on the order rows arrived in.
+  for (const [key, candidates] of keys) keys.set(key, sortDefinitionSummaries(candidates))
+  for (const [alias, candidates] of aliases) aliases.set(alias, sortDefinitionSummaries(candidates))
+  return { keys, aliases }
+}
+
+export function emptyCustomFieldKindIndex(): CustomFieldKindIndex {
+  return { keys: new Map(), aliases: new Map() }
+}
+
+/**
+ * Merges per-source indexes into one, with earlier sources winning a key outright. Callers
+ * pass their sources in the same priority order the value itself resolves in, so a key
+ * defined by more than one source is typed by the source the value actually came from.
+ */
+export function mergeCustomFieldKindIndexes(
+  indexes: Array<CustomFieldKindIndex | null | undefined>,
+): CustomFieldKindIndex {
+  const merged = emptyCustomFieldKindIndex()
+  for (const index of indexes) {
+    if (!index) continue
+    for (const [key, candidates] of index.keys) {
+      if (!merged.keys.has(key)) merged.keys.set(key, candidates)
+    }
+    for (const [alias, candidates] of index.aliases) {
+      if (!merged.aliases.has(alias)) merged.aliases.set(alias, candidates)
+    }
+  }
+  return merged
+}
+
+/**
+ * Flattens the index to the kind map that applies to one scope. The winner per key is the
+ * organization's own definition, then a tenant-scoped one, then a global one — the order
+ * `selectDefinitionForRecord` encodes and the whole codebase resolves definitions by.
+ */
+export function selectCustomFieldKindMap(
+  index: CustomFieldKindIndex | null | undefined,
+  organizationId: string | null | undefined,
+  tenantId: string | null | undefined,
+): CustomFieldKindMap {
+  const map: CustomFieldKindMap = {}
+  if (!index) return map
+  const orgId = organizationId ?? null
+  const tenant = tenantId ?? null
+  for (const [key, candidates] of index.keys) {
+    map[key] = selectDefinitionForRecord(candidates, orgId, tenant)?.kind ?? null
+  }
+  for (const [alias, candidates] of index.aliases) {
+    if (alias in map) continue
+    map[alias] = selectDefinitionForRecord(candidates, orgId, tenant)?.kind ?? null
+  }
+  return map
+}
+
+/**
+ * Memoizing wrapper for the common read shape: many rows, few distinct scopes. A list query
+ * whose rows all share one organization resolves the map once; a global search spanning
+ * organizations resolves one map per organization rather than one per row.
+ */
+export function createCustomFieldKindMapResolver(
+  index: CustomFieldKindIndex | null | undefined,
+): CustomFieldKindMapResolver {
+  const cache = new Map<string, CustomFieldKindMap>()
+  return (organizationId, tenantId) => {
+    const scopeKey = `${organizationId ?? ''}::${tenantId ?? ''}`
+    const cached = cache.get(scopeKey)
+    if (cached) return cached
+    const map = selectCustomFieldKindMap(index, organizationId, tenantId)
+    cache.set(scopeKey, map)
+    return map
+  }
+}
+
+/**
+ * Resolves the `kind` for a `cf:`/`cf_`-prefixed index-document key. Returns `null` when the
+ * key has no active definition — callers then keep the historical no-`kind` behavior rather
+ * than guessing, so an unresolved lookup degrades instead of corrupting the value.
+ */
+export function resolveCustomFieldKind(
+  kinds: CustomFieldKindMap | null | undefined,
+  docKey: string,
+): string | null {
+  if (!kinds) return null
+  const bare = docKey.replace(CF_KEY_PREFIX, '')
+  if (!bare) return null
+  if (bare in kinds) return kinds[bare] ?? null
+  const alias = sanitizeKey(bare)
+  if (alias !== bare && alias in kinds) return kinds[alias] ?? null
+  return null
+}

package/src/lib/encryption/__tests__/indexDoc.custom-field-kinds.test.ts

@@ -0,0 +1,127 @@
+import { decryptIndexDocCustomFields, decryptIndexDocForSearch } from '../indexDoc'
+import { encryptCustomFieldValue } from '../customFieldValues'
+import {
+  buildCustomFieldKindIndex,
+  selectCustomFieldKindMap,
+  type CustomFieldKindRow,
+} from '../../custom-fields/kinds'
+
+function buildCustomFieldKindMap(rows: CustomFieldKindRow[]) {
+  return selectCustomFieldKindMap(buildCustomFieldKindIndex(rows), null, null)
+}
+
+/**
+ * Regression coverage for issue #5968: the query-index and search read paths decrypted
+ * `cf:`/`cf_` values without the field's `kind`, so `decryptCustomFieldValue` fell through
+ * to `JSON.parse` and retyped every string-typed custom field whose plaintext looked like
+ * JSON. Unlike the sibling `indexDoc.test.ts`, this suite does NOT mock
+ * `decryptCustomFieldValue` — the defect lives in the argument the helpers pass to it, so a
+ * mocked value would hide it.
+ */
+
+const fixedKey = Buffer.alloc(32, 7).toString('base64')
+
+const service = {
+  isEnabled: () => true,
+  getDek: async () => ({ key: fixedKey }),
+} as any
+
+const scope = { tenantId: 'tenant-1', organizationId: 'org-1' }
+
+async function encrypt(value: unknown): Promise<unknown> {
+  return encryptCustomFieldValue(value, scope.tenantId, service, new Map())
+}
+
+describe('encryption/indexDoc custom field kinds (#5968)', () => {
+  it.each([
+    ['123', 'text'],
+    ['0042', 'multiline'],
+    ['true', 'select'],
+    ['false', 'text'],
+    ['null', 'text'],
+    ['{"nested":1}', 'multiline'],
+    ['[1,2,3]', 'text'],
+    ['1.5e3', 'currency'],
+  ])('keeps the string %p verbatim for a %s field', async (plaintext, kind) => {
+    const doc = { id: '1', 'cf:note': await encrypt(plaintext) }
+    const kinds = buildCustomFieldKindMap([{ key: 'note', kind }])
+
+    const out = await decryptIndexDocCustomFields(doc, scope, service, new Map(), kinds)
+
+    expect(out['cf:note']).toBe(plaintext)
+  })
+
+  it('still coerces numeric and boolean kinds through the JSON round trip', async () => {
+    const doc = {
+      id: '1',
+      'cf:count': await encrypt(42),
+      'cf:ratio': await encrypt(3.14),
+      'cf:flag': await encrypt(true),
+    }
+    const kinds = buildCustomFieldKindMap([
+      { key: 'count', kind: 'integer' },
+      { key: 'ratio', kind: 'float' },
+      { key: 'flag', kind: 'boolean' },
+    ])
+
+    const out = await decryptIndexDocCustomFields(doc, scope, service, new Map(), kinds)
+
+    expect(out['cf:count']).toBe(42)
+    expect(out['cf:ratio']).toBe(3.14)
+    expect(out['cf:flag']).toBe(true)
+  })
+
+  it('applies the kind to every entry of a multi-value field', async () => {
+    const doc = { id: '1', 'cf:codes': [await encrypt('1'), await encrypt('2')] }
+    const kinds = buildCustomFieldKindMap([{ key: 'codes', kind: 'text' }])
+
+    const out = await decryptIndexDocCustomFields(doc, scope, service, new Map(), kinds)
+
+    expect(out['cf:codes']).toEqual(['1', '2'])
+  })
+
+  it('resolves the sanitized `cf_` alias the hybrid query engine emits', async () => {
+    // `HybridQueryEngine.sanitize()` turns the doc key `cf:order-ref` into `cf_order_ref`,
+    // so a map keyed only by the authored key would miss it.
+    const doc = { id: '1', cf_order_ref: await encrypt('900') }
+    const kinds = buildCustomFieldKindMap([{ key: 'order-ref', kind: 'text' }])
+
+    const out = await decryptIndexDocCustomFields(doc, scope, service, new Map(), kinds)
+
+    expect(out.cf_order_ref).toBe('900')
+  })
+
+  it('falls back to the legacy JSON round trip when the kind cannot be resolved', async () => {
+    const doc = { id: '1', 'cf:unknown': await encrypt('123') }
+
+    const withoutMap = await decryptIndexDocCustomFields(doc, scope, service, new Map())
+    const withEmptyMap = await decryptIndexDocCustomFields(doc, scope, service, new Map(), {})
+
+    expect(withoutMap['cf:unknown']).toBe(123)
+    expect(withEmptyMap['cf:unknown']).toBe(123)
+  })
+
+  it('threads the kind map through decryptIndexDocForSearch', async () => {
+    const searchService = {
+      ...service,
+      isEnabled: () => true,
+      decryptEntityPayload: async () => ({ title: 'Plain' }),
+    } as any
+    const doc = { id: '1', title: 'Encrypted', 'cf:note': await encrypt('123') }
+    const kinds = buildCustomFieldKindMap([{ key: 'note', kind: 'text' }])
+
+    const out = await decryptIndexDocForSearch('example:todo', doc, scope, searchService, new Map(), kinds)
+
+    expect(out.title).toBe('Plain')
+    expect(out['cf:note']).toBe('123')
+  })
+
+  it('threads the kind map through decryptIndexDocForSearch without an entity payload decryptor', async () => {
+    const doc = { id: '1', 'cf:note': await encrypt('true') }
+    const kinds = buildCustomFieldKindMap([{ key: 'note', kind: 'text' }])
+
+    const out = await decryptIndexDocForSearch('example:todo', doc, scope, service, new Map(), kinds)
+
+    expect(out['cf:note']).toBe('true')
+  })
+})