@open-mercato/shared 0.7.0 → 0.7.1-develop.7102.1.b41f7e3e51

package/dist/lib/query/engine.js

@@ -11,6 +11,8 @@ import {
   isSearchFilterOp
 } from "../search/availability.js";
 import { tokenizeText } from "../search/tokenize.js";
+import { fieldNameCandidates } from "./encrypted-sort.js";
+import { isTenantDataEncryptionEnabled } from "../encryption/toggles.js";
 import { runBeforeQueryPipeline, runAfterQueryPipeline } from "./query-extension-runner.js";
 import {
   buildCustomFieldDefinitionIndexFromRows,
@@ -18,11 +20,61 @@ import {
 } from "../crud/custom-field-definition-index.js";
 import { warnOnCiphertextLikeFallback } from "./ciphertext-search-warning.js";
 import { resolveEncryptedSortFields, resolveEncryptedSortMaxRows, sortRowsInMemory } from "./encrypted-sort.js";
+import { resolveListCountCap } from "./count-cap.js";
 import { mapWithConcurrency } from "./bounded-decrypt.js";
+import { parseNumberWithDefault } from "../number.js";
 import { createLogger } from "../logger/index.js";
 const logger = createLogger("shared").child({ component: "query" });
 const DECRYPT_CONCURRENCY = 8;
 const entityTableCache = /* @__PURE__ */ new Map();
+function isEncryptedLikeField(encrypted, field) {
+  return fieldNameCandidates(field).some((candidate) => encrypted.has(candidate));
+}
+const ENCRYPTED_LIKE_FIELDS_TTL_MS = 6e4;
+const ENCRYPTED_LIKE_FIELDS_CACHE_CAP = 500;
+const encryptedLikeFieldsCache = /* @__PURE__ */ new Map();
+async function resolveEncryptedLikeFieldSet(read, entity, tenantId) {
+  const key = `${entity}|${tenantId ?? ""}`;
+  const hit = encryptedLikeFieldsCache.get(key);
+  if (hit && Date.now() - hit.at < ENCRYPTED_LIKE_FIELDS_TTL_MS) return hit.fields;
+  const names = await read();
+  const fields = /* @__PURE__ */ new Set();
+  for (const name of names ?? []) {
+    for (const candidate of fieldNameCandidates(String(name))) fields.add(candidate);
+  }
+  if (encryptedLikeFieldsCache.size >= ENCRYPTED_LIKE_FIELDS_CACHE_CAP) encryptedLikeFieldsCache.clear();
+  encryptedLikeFieldsCache.set(key, { at: Date.now(), fields });
+  return fields;
+}
+function clearEncryptedLikeFieldsCache() {
+  encryptedLikeFieldsCache.clear();
+}
+const COLUMN_EXISTS_CACHE_DEFAULT_TTL_MS = 3e5;
+const COLUMN_EXISTS_CACHE_DEFAULT_MAX_ENTRIES = 1e4;
+const columnExistsCache = /* @__PURE__ */ new Map();
+function resolveColumnExistsCacheTtlMs() {
+  return parseNumberWithDefault(process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MS, COLUMN_EXISTS_CACHE_DEFAULT_TTL_MS, { integer: true, min: 0 });
+}
+function resolveColumnExistsCacheMaxEntries() {
+  return parseNumberWithDefault(process.env.OM_QUERY_COLUMN_EXISTS_CACHE_MAX_ENTRIES, COLUMN_EXISTS_CACHE_DEFAULT_MAX_ENTRIES, { integer: true, min: 1 });
+}
+function storeColumnExists(key, value, ttlMs) {
+  const maxEntries = resolveColumnExistsCacheMaxEntries();
+  if (columnExistsCache.size >= maxEntries) {
+    const now = Date.now();
+    for (const [entryKey, entry] of columnExistsCache) {
+      if (entry.expiresAt <= now) columnExistsCache.delete(entryKey);
+    }
+    if (columnExistsCache.size >= maxEntries) columnExistsCache.clear();
+  }
+  columnExistsCache.set(key, { value, expiresAt: Date.now() + ttlMs });
+}
+function clearColumnExistsCache() {
+  columnExistsCache.clear();
+}
+function columnExistsCacheSize() {
+  return columnExistsCache.size;
+}
 const ENTITY_ID_PATTERN = /^[a-z][a-z0-9_]*:[a-z][a-z0-9_]*$/;
 const isValidEntityIdShape = (value) => ENTITY_ID_PATTERN.test(value);
 const pluralizeBaseName = (name) => {
@@ -139,7 +191,6 @@ class BasicQueryEngine {
     this.em = em;
     this.getDbFn = getDbFn;
     this.resolveEncryptionService = resolveEncryptionService;
-    this.columnCache = /* @__PURE__ */ new Map();
     this.searchAliasSeq = 0;
     this.searchAvailabilityInstance = null;
   }
@@ -232,6 +283,35 @@ class BasicQueryEngine {
     const searchEnabled = !skipAutoScope && await this.searchAvailability().staticEnabled();
     const hasSearchTokens = searchEnabled && searchFilters.length ? await this.searchAvailability().hasTokens(String(entity), opts.tenantId ?? null, orgScope) : false;
     const searchActive = searchEnabled && hasSearchTokens;
+    let encryptedLikeFields = null;
+    if (searchActive && searchConfig.useIlikeForNonEncryptedFields === true && searchFilters.some((filter) => !String(filter.field).startsWith("cf:"))) {
+      try {
+        const service = this.getEncryptionService();
+        const readEncryptedFieldNames = service?.getEncryptedFieldNames?.bind(service);
+        if (readEncryptedFieldNames) {
+          encryptedLikeFields = await resolveEncryptedLikeFieldSet(
+            () => readEncryptedFieldNames(
+              String(entity),
+              opts.tenantId ?? null,
+              null,
+              { ignoreRuntimeHealth: true }
+            ),
+            String(entity),
+            opts.tenantId ?? null
+          );
+        } else if (isTenantDataEncryptionEnabled()) {
+          encryptedLikeFields = null;
+        } else {
+          encryptedLikeFields = /* @__PURE__ */ new Set();
+        }
+      } catch (err) {
+        logger.warn("search: encrypted-field map unavailable; keeping the token rewrite for all columns", {
+          entity: String(entity),
+          error: err instanceof Error ? err.message : String(err)
+        });
+        encryptedLikeFields = null;
+      }
+    }
     if (searchFilters.length) {
       const fields = searchFilters.map((filter) => String(filter.field));
       this.logSearchDebug("search:init", {
@@ -293,7 +373,12 @@ class BasicQueryEngine {
     }
     const recordIdColumn = qualify("id");
     const applyFilterOp = (builder, column, op, value, fieldName) => {
-      if ((op === "like" || op === "ilike") && searchActive && typeof value === "string" && fieldName && typeof column === "string") {
+      if ((op === "like" || op === "ilike") && searchActive && typeof value === "string" && fieldName && typeof column === "string" && // Plaintext columns keep exact SQL ILIKE -- see the encryptedLikeFields note above. cf:*
+      // filters never reach this path (they are applied by the custom-field branches), so this
+      // gate only decides base columns. Membership is tested across name-shape candidates --
+      // encryption maps may declare `displayName` while the filter carries the column name
+      // `display_name`, and a raw comparison would misread that ciphertext column as plaintext.
+      (encryptedLikeFields === null || isEncryptedLikeField(encryptedLikeFields, fieldName))) {
         const tokens = tokenizeText(String(value), searchConfig);
         const hashes = tokens.hashes;
         if (hashes.length) {
@@ -382,6 +467,7 @@ class BasicQueryEngine {
     const sanitize = (s) => s.replace(/[^a-zA-Z0-9_]/g, "_");
     const buildQuery = async (projection) => {
       const isSortKeysProjection = projection === "sortKeys";
+      const isCountProjection = projection === "count";
       let q = db.selectFrom(table);
       if (!skipAutoScope && orgScope && await this.columnExists(table, "organization_id")) {
         q = this.applyOrganizationScope(q, qualify("organization_id"), orgScope);
@@ -455,7 +541,8 @@ class BasicQueryEngine {
         applyJoinFilterOp,
         columnExists: (tbl, column) => this.columnExists(tbl, column)
       });
-      if (isSortKeysProjection) {
+      if (isCountProjection) {
+      } else if (isSortKeysProjection) {
         q = q.select(sql.ref(qualify("id")).as("id"));
         if (await this.columnExists(table, "tenant_id")) {
           q = q.select(sql.ref(qualify("tenant_id")).as("tenant_id"));
@@ -477,18 +564,18 @@ class BasicQueryEngine {
       } else {
         q = q.select(sql`${sql.ref(table)}.*`.as("__all"));
       }
-      const cfSourcesResult = this.configureCustomFieldSources(q, table, entity, db, opts, qualify);
+      const cfSourcesResult = this.configureCustomFieldSources(q, table, entity, db, opts, qualify, !isCountProjection);
       q = cfSourcesResult.builder;
       const cfSources = cfSourcesResult.sources;
       const entityIdToSource = /* @__PURE__ */ new Map();
       for (const source of cfSources) {
         entityIdToSource.set(String(source.entityId), source);
       }
-      const requestedCustomFieldKeys = !isSortKeysProjection && Array.isArray(opts.includeCustomFields) ? opts.includeCustomFields.map((key) => String(key)) : [];
+      const requestedCustomFieldKeys = projection === "full" && Array.isArray(opts.includeCustomFields) ? opts.includeCustomFields.map((key) => String(key)) : [];
       const cfKeys = /* @__PURE__ */ new Set();
       const keySource = /* @__PURE__ */ new Map();
       let resolvedCustomFieldDefinitions2;
-      if (!isSortKeysProjection) {
+      if (projection === "full") {
         for (const f of opts.fields || []) {
           if (typeof f === "string" && f.startsWith("cf:")) cfKeys.add(f.slice(3));
         }
@@ -496,7 +583,7 @@ class BasicQueryEngine {
       for (const f of cfFilters) {
         if (typeof f.field === "string" && f.field.startsWith("cf:")) cfKeys.add(f.field.slice(3));
       }
-      if (!isSortKeysProjection && opts.includeCustomFields === true) {
+      if (projection === "full" && opts.includeCustomFields === true) {
         if (entityIdToSource.size > 0) {
           const entityIdList = Array.from(entityIdToSource.keys());
           const entityOrder = /* @__PURE__ */ new Map();
@@ -595,6 +682,7 @@ class BasicQueryEngine {
       for (const key of cfKeys) {
         const source = keySource.get(key);
         if (!source) continue;
+        if (isCountProjection) continue;
         const entityIdForKey = source.entityId;
         const recordIdExpr = source.recordIdExpr;
         const sourceAliasSafe = sanitize(source.alias || "src");
@@ -642,8 +730,10 @@ class BasicQueryEngine {
       for (const f of regularCfFilters) {
         if (!f.field.startsWith("cf:")) continue;
         const key = f.field.slice(3);
+        const filterSource = keySource.get(key);
+        if (!filterSource) continue;
         const expr = cfValueExprByKey[key];
-        if (!expr) continue;
+        if (!isCountProjection && !expr) continue;
         if ((f.op === "like" || f.op === "ilike") && searchActive && typeof f.value === "string") {
           const tokens = tokenizeText(String(f.value), searchConfig);
           const hashes = tokens.hashes;
@@ -678,15 +768,39 @@ class BasicQueryEngine {
             });
           }
         }
+        if (isCountProjection) {
+          q = this.applyCfValueExistsFilter(q, {
+            source: filterSource,
+            qualify,
+            tenantId: tenantId ?? null,
+            key,
+            op: f.op,
+            value: f.value
+          });
+          continue;
+        }
         q = this.applyColumnOp(q, expr, f.op, f.value);
       }
-      const applicableGroupFilters = resolvedGroupFilters.map((group) => group.filter((rf) => rf.kind !== "cf" || Boolean(cfValueExprByKey[rf.key]))).filter((group) => group.length > 0);
+      const cfLeafApplicable = (key) => isCountProjection ? keySource.has(key) : Boolean(cfValueExprByKey[key]);
+      const applicableGroupFilters = resolvedGroupFilters.map((group) => group.filter((rf) => rf.kind !== "cf" || cfLeafApplicable(rf.key))).filter((group) => group.length > 0);
       if (applicableGroupFilters.length > 0) {
         q = q.where((eb) => {
           const disjuncts = applicableGroupFilters.map((group) => {
             const parts = group.map((rf) => {
               if (rf.kind === "column") return this.buildColumnOpExpression(eb, rf.qualified, rf.op, rf.value);
-              if (rf.kind === "cf") return this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value);
+              if (rf.kind === "cf") {
+                if (isCountProjection) {
+                  return this.buildCfValueExistsExpression(eb, {
+                    source: keySource.get(rf.key),
+                    qualify,
+                    tenantId: tenantId ?? null,
+                    key: rf.key,
+                    op: rf.op,
+                    value: rf.value
+                  });
+                }
+                return this.buildColumnOpExpression(eb, cfValueExprByKey[rf.key], rf.op, rf.value);
+              }
               return this.buildIndexDocOpExpression(eb, {
                 entity: String(entity),
                 field: rf.field,
@@ -703,7 +817,7 @@ class BasicQueryEngine {
           return disjuncts.length === 1 ? disjuncts[0] : eb.or(disjuncts);
         });
       }
-      if (opts.includeExtensions) {
+      if (opts.includeExtensions && !isCountProjection) {
         const { getModules } = await import("@open-mercato/shared/lib/i18n/server");
         const allMods = getModules();
         const allExts = allMods.flatMap((m) => m.entityExtensions || []);
@@ -720,7 +834,7 @@ class BasicQueryEngine {
           );
         }
       }
-      for (const s of resolvedSorts) {
+      for (const s of isCountProjection ? [] : resolvedSorts) {
         if (s.field.startsWith("cf:")) {
           const key = s.field.slice(3);
           const alias = sanitize(`cf:${key}`);
@@ -736,7 +850,7 @@ class BasicQueryEngine {
           if (!requiresPlaintextSort) q = q.orderBy(qualify(s.field), s.dir ?? "asc");
         }
       }
-      const hasJoinedAggregates2 = opts.includeExtensions && (Array.isArray(opts.includeExtensions) ? opts.includeExtensions.length > 0 : true) || Object.keys(cfValueExprByKey).length > 0;
+      const hasJoinedAggregates2 = !isCountProjection && (opts.includeExtensions && (Array.isArray(opts.includeExtensions) ? opts.includeExtensions.length > 0 : true) || Object.keys(cfValueExprByKey).length > 0);
       if (hasJoinedAggregates2) {
         q = q.groupBy(`${table}.id`);
       }
@@ -751,11 +865,24 @@ class BasicQueryEngine {
       cfMultiAliasByAlias,
       resolvedCustomFieldDefinitions
     } = await buildQuery("full");
-    const mayMultiplyBaseRows = hasJoinedAggregates || Array.isArray(opts.joins) && opts.joins.length > 0 || Array.isArray(opts.customFieldSources) && opts.customFieldSources.length > 0;
-    const countExpr = mayMultiplyBaseRows ? sql`count(distinct ${sql.ref(`${table}.id`)})` : sql`count(*)`;
-    const countBuilder = hasJoinedAggregates ? qFull.clearSelect().clearOrderBy().clearGroupBy().select(countExpr.as("count")) : qFull.clearSelect().clearOrderBy().select(countExpr.as("count"));
-    const countRow = await countBuilder.executeTakeFirst();
-    const total = Number(countRow?.count ?? 0);
+    const countCap = resolveListCountCap();
+    const { builder: countShape } = await buildQuery("count");
+    let total;
+    let listCountCapWarning;
+    if (countCap !== null) {
+      const probe = countShape.select(sql`1`.as("one")).limit(countCap + 1);
+      const countRow = await db.selectFrom(probe.as("om_count_probe")).select(sql`count(*)`.as("count")).executeTakeFirst();
+      const probed = Number(countRow?.count ?? 0);
+      if (probed > countCap) {
+        total = countCap;
+        listCountCapWarning = { entity, cap: countCap };
+      } else {
+        total = probed;
+      }
+    } else {
+      const countRow = await countShape.select(sql`count(*)`.as("count")).executeTakeFirst();
+      total = Number(countRow?.count ?? 0);
+    }
     const svc = encryptionService;
     const decryptPayload = svc?.decryptEntityPayload?.bind(svc);
     const decryptRow = async (item) => {
@@ -804,13 +931,15 @@ class BasicQueryEngine {
       const cap = resolveEncryptedSortMaxRows();
       let qSort = (await buildQuery("sortKeys")).builder;
       if (cap !== null) {
-        qSort = qSort.limit(cap).orderBy(qualify("id"), "asc");
+        qSort = qSort.limit(cap + 1).orderBy(qualify("id"), "asc");
       }
-      const candidateRows = await qSort.execute();
+      const candidateRowsRaw = await qSort.execute();
+      const sortTruncated = cap !== null && candidateRowsRaw.length > cap;
+      const candidateRows = sortTruncated && cap !== null ? candidateRowsRaw.slice(0, cap) : candidateRowsRaw;
       const decryptedCandidates = decryptPayload ? await mapWithConcurrency(candidateRows, DECRYPT_CONCURRENCY, decryptRow) : candidateRows;
       const orderedCandidates = sortRowsInMemory(decryptedCandidates, resolvedSorts);
       const pageIds = orderedCandidates.slice((page - 1) * pageSize, page * pageSize).map((row) => row.id);
-      if (cap !== null && total > cap) {
+      if (sortTruncated && cap !== null) {
         encryptedSortRowCapWarning = {
           entity,
           sortFields: resolvedSorts.map((s) => s.field),
@@ -834,8 +963,10 @@ class BasicQueryEngine {
       pagedItems = decryptPayload ? await mapWithConcurrency(items, DECRYPT_CONCURRENCY, decryptRow) : items;
     }
     let queryResult = { items: pagedItems, page, pageSize, total };
-    if (encryptedSortRowCapWarning) {
-      const meta = { encryptedSortRowCapWarning };
+    if (encryptedSortRowCapWarning || listCountCapWarning) {
+      const meta = {};
+      if (encryptedSortRowCapWarning) meta.encryptedSortRowCapWarning = encryptedSortRowCapWarning;
+      if (listCountCapWarning) meta.listCountCapWarning = listCountCapWarning;
       queryResult.meta = meta;
     }
     if (ext && extensionCtx) {
@@ -880,6 +1011,101 @@ class BasicQueryEngine {
         return builder;
     }
   }
+  /**
+   * Apply a `cf:*` filter as a correlated EXISTS semi-join over
+   * `custom_field_values` (+ `custom_field_defs` for kind-based coercion) —
+   * the count shape's equivalent of the projection path's leftJoin + WHERE.
+   * A semi-join returns each base row at most once, so the count query needs
+   * no DISTINCT or GROUP BY and stays boundable by an outer LIMIT.
+   *
+   * Predicates satisfied by the *absence* of a value row (`eq null`,
+   * `exists: false`) become `NOT EXISTS(value) OR EXISTS(null value)`,
+   * matching the leftJoin form where a missing row yields a NULL expression.
+   */
+  applyCfValueExistsFilter(q, opts) {
+    return q.where((eb) => this.buildCfValueExistsExpression(eb, opts));
+  }
+  /**
+   * Expression-returning core of `applyCfValueExistsFilter`, so a cf leaf
+   * inside an OR group can compile to an EXISTS predicate on the count shape
+   * instead of being dropped for lacking a `cfValueExprByKey` entry.
+   */
+  buildCfValueExistsExpression(eb, opts) {
+    const { source, qualify, tenantId, key, op, value } = opts;
+    const seq = this.searchAliasSeq++;
+    const valAlias = `cfev_${seq}`;
+    const defAlias = `cfed_${seq}`;
+    const srcAlias = `cfes_${seq}`;
+    const caseExpr = sql`CASE ${sql.ref(`${defAlias}.kind`)}
+         WHEN 'integer' THEN (${sql.ref(`${valAlias}.value_int`)})::text
+         WHEN 'float' THEN (${sql.ref(`${valAlias}.value_float`)})::text
+         WHEN 'boolean' THEN (${sql.ref(`${valAlias}.value_bool`)})::text
+         WHEN 'multiline' THEN (${sql.ref(`${valAlias}.value_multiline`)})::text
+         ELSE (${sql.ref(`${valAlias}.value_text`)})::text
+       END`;
+    const buildSub = (eb2) => {
+      let sub = eb2.selectFrom(`custom_field_values as ${valAlias}`).select(sql`1`.as("one")).leftJoin(`custom_field_defs as ${defAlias}`, (jb) => jb.on(`${defAlias}.entity_id`, "=", String(source.entityId)).on(`${defAlias}.key`, "=", key).on(`${defAlias}.is_active`, "=", true).on((jeb) => jeb.or([
+        jeb(`${defAlias}.tenant_id`, "=", tenantId),
+        jeb(`${defAlias}.tenant_id`, "is", null)
+      ]))).where(`${valAlias}.entity_id`, "=", String(source.entityId)).where(`${valAlias}.field_key`, "=", key).where((web) => web.or([
+        web(`${valAlias}.tenant_id`, "=", tenantId),
+        web(`${valAlias}.tenant_id`, "is", null)
+      ]));
+      if (source.hop) {
+        sub = sub.innerJoin(`${source.table} as ${srcAlias}`, (jb) => jb.on(sql`${sql.ref(`${valAlias}.record_id`)} = (${sql.ref(`${srcAlias}.${source.hop.recordIdColumn}`)})::text`)).whereRef(`${srcAlias}.${source.hop.toField}`, "=", qualify(source.hop.fromField));
+      } else {
+        sub = sub.where(sql`${sql.ref(`${valAlias}.record_id`)} = ${source.recordIdExpr}`);
+      }
+      return sub;
+    };
+    const absenceSatisfiable = op === "eq" && value === null || op === "exists" && !value;
+    if (absenceSatisfiable) {
+      return eb.or([
+        eb.not(eb.exists(buildSub(eb))),
+        eb.exists(buildSub(eb).where(sql`${caseExpr} is null`))
+      ]);
+    }
+    let predicate = null;
+    switch (op) {
+      case "eq":
+        predicate = sql`${caseExpr} = ${value}`;
+        break;
+      case "ne":
+        predicate = value === null ? sql`${caseExpr} is not null` : sql`${caseExpr} != ${value}`;
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        const operator = sql.raw(op === "gt" ? ">" : op === "gte" ? ">=" : op === "lt" ? "<" : "<=");
+        predicate = sql`${caseExpr} ${operator} ${value}`;
+        break;
+      }
+      case "in": {
+        const vals = Array.isArray(value) ? value : [value];
+        predicate = sql`${caseExpr} in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`;
+        break;
+      }
+      case "nin": {
+        const vals = Array.isArray(value) ? value : [value];
+        predicate = sql`${caseExpr} not in (${sql.join(vals.map((v) => sql`${v}`), sql`, `)})`;
+        break;
+      }
+      case "like":
+        predicate = sql`${caseExpr} like ${value}`;
+        break;
+      case "ilike":
+        predicate = sql`${caseExpr} ilike ${value}`;
+        break;
+      case "exists":
+        predicate = sql`${caseExpr} is not null`;
+        break;
+      default:
+        return eb.val(true);
+    }
+    const captured = predicate;
+    return eb.exists(buildSub(eb).where(captured));
+  }
   buildColumnOpExpression(eb, column, op, value) {
     switch (op) {
       case "eq":
@@ -915,16 +1141,13 @@ class BasicQueryEngine {
   }
   async columnExists(table, column) {
     const key = `${table}.${column}`;
-    if (this.columnCache.has(key)) {
-      const cached = this.columnCache.get(key);
-      if (cached === true) return true;
-      this.columnCache.delete(key);
-    }
+    const ttlMs = resolveColumnExistsCacheTtlMs();
+    const cached = columnExistsCache.get(key);
+    if (cached && cached.expiresAt > Date.now()) return cached.value;
     const db = this.getDb();
     const exists = await db.selectFrom("information_schema.columns").select(sql`1`.as("one")).where("table_name", "=", table).where("column_name", "=", column).limit(1).executeTakeFirst();
     const present = !!exists;
-    if (present) this.columnCache.set(key, true);
-    else this.columnCache.delete(key);
+    if (ttlMs > 0) storeColumnExists(key, present, ttlMs);
     return present;
   }
   applySearchTokens(q, opts) {
@@ -1061,7 +1284,7 @@ class BasicQueryEngine {
       return sub;
     })());
   }
-  configureCustomFieldSources(q, baseTable, baseEntity, db, opts, qualify) {
+  configureCustomFieldSources(q, baseTable, baseEntity, db, opts, qualify, attachJoins = true) {
     const sources = [
       {
         entityId: baseEntity,
@@ -1079,14 +1302,22 @@ class BasicQueryEngine {
       if (!join) {
         throw new Error(`QueryEngine: customFieldSources entry for ${String(srcOpt.entityId)} requires a join configuration`);
       }
-      const joinFn = (join.type ?? "left") === "inner" ? "innerJoin" : "leftJoin";
-      next = next[joinFn](`${joinTable} as ${alias}`, (jb) => jb.onRef(`${alias}.${join.toField}`, "=", qualify(join.fromField)));
+      const joinType = (join.type ?? "left") === "inner" ? "inner" : "left";
+      if (attachJoins) {
+        const joinFn = joinType === "inner" ? "innerJoin" : "leftJoin";
+        next = next[joinFn](`${joinTable} as ${alias}`, (jb) => jb.onRef(`${alias}.${join.toField}`, "=", qualify(join.fromField)));
+      } else if (joinType === "inner") {
+        next = next.where((eb) => eb.exists(
+          eb.selectFrom(`${joinTable} as ${alias}`).select(sql`1`.as("one")).whereRef(`${alias}.${join.toField}`, "=", qualify(join.fromField))
+        ));
+      }
       const recordColumn = srcOpt.recordIdColumn ?? "id";
       sources.push({
         entityId: srcOpt.entityId,
         alias,
         table: joinTable,
-        recordIdExpr: sql`${sql.ref(`${alias}.${recordColumn}`)}::text`
+        recordIdExpr: sql`${sql.ref(`${alias}.${recordColumn}`)}::text`,
+        hop: { fromField: join.fromField, toField: join.toField, recordIdColumn: recordColumn, type: joinType }
       });
     });
     return { builder: next, sources };
@@ -1126,7 +1357,12 @@ class BasicQueryEngine {
 export {
   BasicQueryEngine,
   ENTITY_ID_PATTERN,
+  clearColumnExistsCache,
+  clearEncryptedLikeFieldsCache,
+  columnExistsCacheSize,
+  isEncryptedLikeField,
   isValidEntityIdShape,
+  resolveEncryptedLikeFieldSet,
   resolveEntityTableName,
   resolveRegisteredEntityTableName
 };