@objectstack/service-analytics 17.0.0-rc.3 → 17.0.0-rc.5

package/dist/index.cjs

@@ -41,7 +41,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/analytics-service.ts
-var import_data3 = require("@objectstack/spec/data");
+var import_data4 = require("@objectstack/spec/data");
 var import_core5 = require("@objectstack/core");
 
 // src/cube-registry.ts
@@ -160,6 +160,14 @@ var CubeRegistry = class {
 };
 
 // src/strategies/filter-normalizer.ts
+var import_data = require("@objectstack/spec/data");
+var import_api = require("@objectstack/spec/api");
+function invalidFilterError(message) {
+  const err = new Error(message);
+  err.code = import_api.StandardErrorCode.enum.INVALID_FILTER;
+  err.status = 400;
+  return err;
+}
 var MONGO_TO_CUBE_OP = {
   $eq: "equals",
   $ne: "notEquals",
@@ -174,12 +182,21 @@ var MONGO_TO_CUBE_OP = {
   $startsWith: "startsWith",
   $endsWith: "endsWith"
 };
-function stringifyForCube(v) {
-  if (v == null) return "";
-  if (typeof v === "boolean") return v ? "true" : "false";
-  if (v instanceof Date) return v.toISOString();
-  if (typeof v === "object") return JSON.stringify(v);
-  return String(v);
+function comparand(v) {
+  return v === void 0 ? null : v;
+}
+var SQL_CONST_FALSE = "1 = 0";
+var SQL_CONST_TRUE = "1 = 1";
+function falseNode() {
+  return { kind: "const", value: false };
+}
+function notOf(inner) {
+  if (!inner) return falseNode();
+  if (inner.kind === "const") return { kind: "const", value: !inner.value };
+  return { kind: "not", child: inner };
+}
+function isFilterObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
 }
 function andOf(children) {
   if (children.length === 0) return null;
@@ -197,18 +214,23 @@ function fieldLeaves(key, raw) {
   }
   if (typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
     const wrapper = raw;
+    if (Object.keys(wrapper).length === 0) {
+      throw invalidFilterError(
+        `[analytics] "${key}" carries a field constraint with zero operators ({}). Refusing rather than reading it as "every row" or "no row" \u2014 #5240 ruled this shape refused on every backend.`
+      );
+    }
     const opKeys = Object.keys(wrapper).filter((k) => k.startsWith("$"));
     if (opKeys.length > 0) {
       for (const opKey of opKeys) {
         if (opKey === "$between") {
           const v2 = wrapper[opKey];
           if (!Array.isArray(v2) || v2.length !== 2) {
-            throw new Error(
+            throw invalidFilterError(
               `[analytics] "$between" on "${key}" needs a two-element [min, max] array, got ${JSON.stringify(v2)}. Dropping the predicate would silently widen the query to every row.`
             );
           }
-          leaf("gte", [stringifyForCube(v2[0])]);
-          leaf("lte", [stringifyForCube(v2[1])]);
+          leaf("gte", [comparand(v2[0])]);
+          leaf("lte", [comparand(v2[1])]);
           continue;
         }
         if (opKey === "$null" || opKey === "$exists") {
@@ -216,14 +238,33 @@ function fieldLeaves(key, raw) {
           leaf(isNull ? "notSet" : "set", []);
           continue;
         }
+        if ((opKey === "$eq" || opKey === "$ne") && wrapper[opKey] === null) {
+          leaf(opKey === "$eq" ? "notSet" : "set", []);
+          continue;
+        }
+        if ((opKey === "$in" || opKey === "$nin") && Array.isArray(wrapper[opKey]) && wrapper[opKey].length === 0) {
+          out.push({ kind: "const", value: opKey === "$nin" });
+          continue;
+        }
         const cubeOp = MONGO_TO_CUBE_OP[opKey];
         if (!cubeOp) {
-          throw new Error(
+          throw invalidFilterError(
             `[analytics] Unsupported filter operator "${opKey}" on "${key}". Supported: ${Object.keys(MONGO_TO_CUBE_OP).join(", ")}, $between, $null, $exists, and the $and/$or/$not combinators. Dropping it would silently widen the query to rows the filter excludes.`
           );
         }
         const v = wrapper[opKey];
-        leaf(cubeOp, Array.isArray(v) ? v.map(stringifyForCube) : [stringifyForCube(v)]);
+        const values = Array.isArray(v) ? v.map(comparand) : [comparand(v)];
+        if (nullValueSatisfiesOperator(opKey, v) && !operatorIsNullTotal(opKey, v)) {
+          out.push({
+            kind: "or",
+            children: [
+              { kind: "leaf", member: key, operator: "notSet", values: [] },
+              { kind: "leaf", member: key, operator: cubeOp, values }
+            ]
+          });
+          continue;
+        }
+        leaf(cubeOp, values);
       }
       return out;
     }
@@ -232,8 +273,10 @@ function fieldLeaves(key, raw) {
     }
     return out;
   }
-  if (Array.isArray(raw)) leaf("in", raw.map(stringifyForCube));
-  else leaf("equals", [stringifyForCube(raw)]);
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) out.push({ kind: "const", value: false });
+    else leaf("in", raw.map(comparand));
+  } else leaf("equals", [comparand(raw)]);
   return out;
 }
 function buildNode(cond) {
@@ -241,24 +284,42 @@ function buildNode(cond) {
   for (const [key, raw] of Object.entries(cond)) {
     if (raw === void 0) continue;
     if (key === "$and" || key === "$or") {
-      if (!Array.isArray(raw) || raw.length === 0) {
-        throw new Error(
-          `[analytics] "${key}" requires a non-empty array. An empty combinator has no defensible reading \u2014 dropping it widens the query, and treating it as "match nothing" silently empties a chart.`
+      if (!Array.isArray(raw)) {
+        throw invalidFilterError(
+          `[analytics] "${key}" requires an array of filter objects, got ${JSON.stringify(raw)}. Dropping it would silently widen the query to rows the filter excludes.`
         );
       }
-      const branches = raw.map((sub) => sub && typeof sub === "object" ? buildNode(sub) : null).filter((n) => n !== null);
-      if (branches.length === 0) continue;
-      if (key === "$and") children.push(...branches);
-      else children.push(branches.length === 1 ? branches[0] : { kind: "or", children: branches });
+      if (raw.length === 0) {
+        if (key === "$or") children.push(falseNode());
+        continue;
+      }
+      const branches = raw.map((sub) => {
+        if (!isFilterObject(sub)) {
+          throw invalidFilterError(
+            `[analytics] "${key}" branches must be filter objects, got ${JSON.stringify(sub)}. Skipping it would silently change which rows the filter admits.`
+          );
+        }
+        return buildNode(sub);
+      });
+      if (key === "$or" && branches.some((n) => n === null)) continue;
+      const kept = branches.filter((n) => n !== null);
+      if (kept.length === 0) continue;
+      if (key === "$and") children.push(...kept);
+      else children.push(kept.length === 1 ? kept[0] : { kind: "or", children: kept });
       continue;
     }
     if (key === "$not") {
-      const inner = raw && typeof raw === "object" ? buildNode(raw) : null;
-      if (inner) children.push({ kind: "not", child: inner });
+      if (!isFilterObject(raw)) {
+        throw invalidFilterError(
+          `[analytics] "$not" requires a filter object, got ${JSON.stringify(raw)}. Dropping it would silently widen the query to rows the filter excludes.`
+        );
+      }
+      const inner = buildNode(nullSafeNegationOperand(raw));
+      children.push(notOf(inner));
       continue;
     }
     if (key.startsWith("$")) {
-      throw new Error(
+      throw invalidFilterError(
         `[analytics] Unsupported top-level filter operator "${key}". Dropping it would silently widen the query to rows the filter excludes.`
       );
     }
@@ -266,43 +327,194 @@ function buildNode(cond) {
   }
   return andOf(children);
 }
-function normalizeAnalyticsFilterTree(query) {
+function nullValueSatisfiesOperator(op, value) {
+  switch (op) {
+    // [#5332] `$eq: null` IS the null predicate — a NULL column satisfies it,
+    // and no other comparand does.
+    case "$eq":
+      return value === null;
+    // Mirror image: `$ne: null` compiles to `set` (`IS NOT NULL`), which a NULL
+    // column FAILS. Any other comparand is the two-valued JS `!==`, which an
+    // absent value passes — the arm this used to be for every comparand.
+    case "$ne":
+      return value !== null;
+    case "$null":
+      return value === true;
+    case "$exists":
+      return value === false;
+    // Negative-polarity set / substring tests hold vacuously for an absent value.
+    case "$nin":
+      return true;
+    // `$notContains` is the one operator where the two JS backends disagree for
+    // a null-valued field (`driver-memory` answers false, `formula` true).
+    // `formula` is followed because `driver-sql` and `read-scope-sql` follow it,
+    // so this module casts no vote on a disagreement that is filed elsewhere.
+    case "$notContains":
+      return true;
+    default:
+      return false;
+  }
+}
+function operatorIsNullTotal(op, value) {
+  switch (op) {
+    // Compile to `set` / `notSet` — `IS NULL` / `IS NOT NULL`, two-valued by
+    // construction, on every strategy that compiles this tree.
+    case "$null":
+    case "$exists":
+      return true;
+    // [#5332] A `null` comparand makes these null PREDICATES too — `notSet` /
+    // `set`, not comparisons — so they are total by construction and take NO
+    // guard. Left out, `{$not: {stage: {$eq: null}}}` wrapped `stage IS NOT NULL
+    // AND stage IS NULL` (an always-false conjunction) and negated it to EVERY
+    // row, for a filter meaning "stage is not empty".
+    case "$eq":
+    case "$ne":
+      return value === null;
+    // An EMPTY set compiles to a boolean CONSTANT (see `fieldLeaves`), and a
+    // constant is total. Wrapping a guard around it would only add a redundant
+    // conjunct to a predicate whose value is already decided.
+    case "$in":
+    case "$nin":
+      return Array.isArray(value) && value.length === 0;
+    default:
+      return false;
+  }
+}
+function nullGuardForFieldSpec(spec) {
+  if (spec === null) return "none";
+  if (Array.isArray(spec)) return spec.length === 0 ? "none" : "requireValue";
+  if (typeof spec !== "object" || spec instanceof Date) return "requireValue";
+  const entries = Object.entries(spec);
+  if (entries.length === 0) return "none";
+  let total = true;
+  let nullSatisfies = true;
+  for (const [op, value] of entries) {
+    if (!operatorIsNullTotal(op, value)) total = false;
+    if (!nullValueSatisfiesOperator(op, value)) nullSatisfies = false;
+  }
+  if (total) return "none";
+  return nullSatisfies ? "allowNull" : "requireValue";
+}
+function guardFieldEntry(key, spec, out, guarded) {
+  if (isFilterObject(spec) && Object.keys(spec).length > 0 && !Object.keys(spec).some((k) => k.startsWith("$"))) {
+    for (const [nested, value] of Object.entries(spec)) {
+      guardFieldEntry(`${key}.${nested}`, value, out, guarded);
+    }
+    return;
+  }
+  const guard = nullGuardForFieldSpec(spec);
+  if (guard === "none") {
+    out[key] = spec;
+  } else if (guard === "requireValue") {
+    guarded.push({ [key]: { $null: false } }, { [key]: spec });
+  } else {
+    guarded.push({ $or: [{ [key]: { $null: true } }, { [key]: spec }] });
+  }
+}
+function nullSafeNegationOperand(node) {
+  const out = {};
+  const guarded = [];
+  for (const [key, value] of Object.entries(node)) {
+    if ((key === "$and" || key === "$or") && Array.isArray(value)) {
+      out[key] = value.map((element) => isFilterObject(element) ? nullSafeNegationOperand(element) : element);
+      continue;
+    }
+    if (key.startsWith("$")) {
+      out[key] = value;
+      continue;
+    }
+    guardFieldEntry(key, value, out, guarded);
+  }
+  if (guarded.length > 0) {
+    const existing = Array.isArray(out.$and) ? out.$and : [];
+    out.$and = [...existing, ...guarded];
+  }
+  return out;
+}
+function filterArrayNotLowerableError(where) {
+  return invalidFilterError(
+    `[analytics] received a 'where' array that is not a filter: ${JSON.stringify(where)}. A filter array is a comparison [field, operator, value], a logical node ["and"|"or", ...conditions], or a list of those \u2014 it is INPUT-ONLY sugar (spec 'FilterArray'), lowered to a FilterCondition by @objectstack/spec parseFilterAST() at every door, this one included (#5158/#5334). This value cannot be lowered, and an unapplied filter would have charted the UNFILTERED dataset. Recognised operators: ${[...import_data.VALID_AST_OPERATORS].sort().join(", ")}. Infix joins ([condA, "or", condB]) are NOT one of the shapes \u2014 write the prefix form ["or", condA, condB].`
+  );
+}
+function lowerAnalyticsWhere(query) {
   if (!query || typeof query !== "object") return null;
   const where = query.where;
-  if (!where || typeof where !== "object" || Array.isArray(where)) return null;
-  return buildNode(where);
+  if (!where || typeof where !== "object") return null;
+  if (Array.isArray(where)) {
+    if (where.length === 0) return null;
+    if (!(0, import_data.isFilterAST)(where)) throw filterArrayNotLowerableError(where);
+    const condition = (0, import_data.parseFilterAST)(where);
+    if (!condition || typeof condition !== "object" || Array.isArray(condition)) {
+      throw invalidFilterError(
+        `[analytics] filter array ${JSON.stringify(where)} passed isFilterAST() but parseFilterAST() lowered it to ${JSON.stringify(condition)}. Refusing rather than charting the dataset unfiltered (#5158/#5334).`
+      );
+    }
+    return condition;
+  }
+  return where;
+}
+function conjunctFieldKeys(condition) {
+  const keys = [];
+  const walk = (cond) => {
+    for (const [key, value] of Object.entries(cond)) {
+      if (key === "$and" && Array.isArray(value)) {
+        for (const child of value) {
+          if (isFilterObject(child)) walk(child);
+        }
+        continue;
+      }
+      if (key.startsWith("$")) continue;
+      keys.push(key);
+    }
+  };
+  walk(condition);
+  return keys;
+}
+function normalizeAnalyticsFilterTree(query) {
+  const condition = lowerAnalyticsWhere(query);
+  if (!condition) return null;
+  return buildNode(condition);
 }
 function collectFilterLeaves(node) {
   if (!node) return [];
   if (node.kind === "leaf") return [{ member: node.member, operator: node.operator, values: node.values }];
+  if (node.kind === "const") return [];
   if (node.kind === "not") return collectFilterLeaves(node.child);
   return node.children.flatMap(collectFilterLeaves);
 }
-function recoverNumber(s) {
-  if (/^-?\d+(\.\d+)?$/.test(s)) {
-    const n = Number(s);
-    if (Number.isFinite(n)) return n;
-  }
-  return void 0;
+function toSqlBindValue(v) {
+  if (typeof v === "boolean") return v ? 1 : 0;
+  if (v instanceof Date) return v.toISOString();
+  if (v !== null && typeof v === "object") return JSON.stringify(v);
+  return v;
 }
-function coerceFilterValueForSql(s) {
-  if (s === "true") return 1;
-  if (s === "false") return 0;
-  if (s === "null") return null;
-  return recoverNumber(s) ?? s;
+
+// src/like-pattern.ts
+var LIKE_ESCAPE_CHAR = "\\";
+function escapeLikePattern(value) {
+  return String(value).replace(/[\\%_]/g, "\\$&");
 }
-function coerceFilterValueForObjectQL(s) {
-  if (s === "true") return true;
-  if (s === "false") return false;
-  if (s === "null") return null;
-  return recoverNumber(s) ?? s;
+function likePattern(shape, value) {
+  const escaped = escapeLikePattern(value);
+  return shape === "starts" ? `${escaped}%` : shape === "ends" ? `%${escaped}` : `%${escaped}%`;
 }
 
 // src/read-scope-sql.ts
 var IDENT = /^[a-z_][a-z0-9_]*$/i;
+var READ_SCOPE_COMPILE_FAILED = "READ_SCOPE_COMPILE_FAILED";
+function readScopeCompileError(message) {
+  const err = new Error(message);
+  err.code = READ_SCOPE_COMPILE_FAILED;
+  err.status = 500;
+  return err;
+}
+var FALSE_CLAUSE = "1 = 0";
+function isFilterNode(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
 function quoteIdent(name, kind) {
   if (typeof name !== "string" || !IDENT.test(name)) {
-    throw new Error(`[read-scope-sql] unsafe ${kind} identifier "${String(name)}" \u2014 refusing to build read scope (fail-closed).`);
+    throw readScopeCompileError(`[read-scope-sql] unsafe ${kind} identifier "${String(name)}" \u2014 refusing to build read scope (fail-closed).`);
   }
   return `"${name}"`;
 }
@@ -312,25 +524,43 @@ function compileScopedFilterToSql(filter, alias) {
   const sql = compileNode(filter, quotedAlias, params);
   return { sql, params };
 }
+function compileSub(node, qAlias) {
+  const params = [];
+  const sql = compileNode(node, qAlias, params);
+  return { sql, params };
+}
 function compileNode(node, qAlias, params) {
-  if (node === null || typeof node !== "object" || Array.isArray(node)) {
-    throw new Error("[read-scope-sql] read scope must be a filter object (fail-closed).");
+  if (!isFilterNode(node)) {
+    throw readScopeCompileError("[read-scope-sql] read scope must be a filter object (fail-closed).");
   }
   const clauses = [];
   for (const [key, value] of Object.entries(node)) {
     if (key === "$and" || key === "$or") {
-      if (!Array.isArray(value) || value.length === 0) {
-        throw new Error(`[read-scope-sql] "${key}" requires a non-empty array (fail-closed).`);
+      if (!Array.isArray(value)) {
+        throw readScopeCompileError(`[read-scope-sql] "${key}" requires an array (fail-closed).`);
       }
-      const parts = value.map((child) => compileNode(child, qAlias, params)).filter((s) => s.length > 0);
-      if (parts.length === 0) continue;
+      if (value.length === 0) {
+        if (key === "$or") clauses.push(FALSE_CLAUSE);
+        continue;
+      }
+      const compiled = value.map((child) => compileSub(child, qAlias));
+      if (key === "$or" && compiled.some((c) => c.sql.length === 0)) continue;
+      const kept = compiled.filter((c) => c.sql.length > 0);
+      if (kept.length === 0) continue;
+      for (const part of kept) params.push(...part.params);
       const joiner = key === "$and" ? " AND " : " OR ";
-      clauses.push(`(${parts.join(joiner)})`);
+      clauses.push(`(${kept.map((c) => c.sql).join(joiner)})`);
     } else if (key === "$not") {
-      const inner = compileNode(value, qAlias, params);
-      if (inner) clauses.push(`NOT (${inner})`);
+      const operand = isFilterNode(value) ? nullSafeNegationOperand2(value) : value;
+      const inner = compileSub(operand, qAlias);
+      if (inner.sql.length === 0) {
+        clauses.push(FALSE_CLAUSE);
+      } else {
+        params.push(...inner.params);
+        clauses.push(`NOT (${inner.sql})`);
+      }
     } else if (key.startsWith("$")) {
-      throw new Error(`[read-scope-sql] unsupported top-level operator "${key}" (fail-closed).`);
+      throw readScopeCompileError(`[read-scope-sql] unsupported top-level operator "${key}" (fail-closed).`);
     } else {
       clauses.push(compileField(key, value, qAlias, params));
     }
@@ -345,12 +575,12 @@ function compileField(field, value, qAlias, params) {
     return `${col} = ?`;
   }
   if (Array.isArray(value)) {
-    throw new Error(`[read-scope-sql] bare array value for "${field}" \u2014 use { $in: [...] } (fail-closed).`);
+    throw readScopeCompileError(`[read-scope-sql] bare array value for "${field}" \u2014 use { $in: [...] } (fail-closed).`);
   }
   const ops = value;
   const keys = Object.keys(ops);
   if (keys.length === 0 || keys.some((k) => !k.startsWith("$"))) {
-    throw new Error(`[read-scope-sql] "${field}" has a nested/relation value which is not supported in a read scope (fail-closed).`);
+    throw readScopeCompileError(`[read-scope-sql] "${field}" has a nested/relation value which is not supported in a read scope (fail-closed).`);
   }
   const parts = [];
   for (const op of keys) {
@@ -362,12 +592,20 @@ function bind(params, v) {
   params.push(v);
   return "?";
 }
+function bindLike(params, pattern) {
+  return `${bind(params, pattern)} ESCAPE ${bind(params, LIKE_ESCAPE_CHAR)}`;
+}
+function nullSafeNegative(col, test) {
+  return `(${col} IS NULL OR ${test})`;
+}
 function compileOperator(col, op, val, field, params) {
   switch (op) {
     case "$eq":
       return val === null ? `${col} IS NULL` : `${col} = ${bind(params, val)}`;
+    // [#5298] `$ne: null` stays `IS NOT NULL` — already total, and "has any
+    // value" is false for a row that has none. Only the comparison is guarded.
     case "$ne":
-      return val === null ? `${col} IS NOT NULL` : `${col} <> ${bind(params, val)}`;
+      return val === null ? `${col} IS NOT NULL` : nullSafeNegative(col, `${col} <> ${bind(params, val)}`);
     case "$gt":
       return `${col} > ${bind(params, val)}`;
     case "$gte":
@@ -377,35 +615,139 @@ function compileOperator(col, op, val, field, params) {
     case "$lte":
       return `${col} <= ${bind(params, val)}`;
     case "$in": {
-      if (!Array.isArray(val)) throw new Error(`[read-scope-sql] $in for "${field}" needs an array (fail-closed).`);
-      if (val.length === 0) return "1 = 0";
+      if (!Array.isArray(val)) throw readScopeCompileError(`[read-scope-sql] $in for "${field}" needs an array (fail-closed).`);
+      if (val.length === 0) return FALSE_CLAUSE;
       return `${col} IN (${val.map((v) => bind(params, v)).join(", ")})`;
     }
     case "$nin": {
-      if (!Array.isArray(val)) throw new Error(`[read-scope-sql] $nin for "${field}" needs an array (fail-closed).`);
+      if (!Array.isArray(val)) throw readScopeCompileError(`[read-scope-sql] $nin for "${field}" needs an array (fail-closed).`);
       if (val.length === 0) return "1 = 1";
-      return `${col} NOT IN (${val.map((v) => bind(params, v)).join(", ")})`;
+      return nullSafeNegative(col, `${col} NOT IN (${val.map((v) => bind(params, v)).join(", ")})`);
     }
     case "$between": {
-      if (!Array.isArray(val) || val.length !== 2) throw new Error(`[read-scope-sql] $between for "${field}" needs [min,max] (fail-closed).`);
+      if (!Array.isArray(val) || val.length !== 2) throw readScopeCompileError(`[read-scope-sql] $between for "${field}" needs [min,max] (fail-closed).`);
       return `${col} BETWEEN ${bind(params, val[0])} AND ${bind(params, val[1])}`;
     }
+    // [#5567] The comparand is a LITERAL, so it is escaped and the escape
+    // character is bound with it. See {@link bindLike}.
     case "$contains":
-      return `${col} LIKE ${bind(params, `%${String(val)}%`)}`;
+      return `${col} LIKE ${bindLike(params, likePattern("contains", val))}`;
+    // [#5298] NULL-safe: `NOT LIKE` is UNKNOWN for a NULL column, and "does not
+    // contain" is true of a value that is not there.
     case "$notContains":
-      return `${col} NOT LIKE ${bind(params, `%${String(val)}%`)}`;
+      return nullSafeNegative(col, `${col} NOT LIKE ${bindLike(params, likePattern("contains", val))}`);
     case "$startsWith":
-      return `${col} LIKE ${bind(params, `${String(val)}%`)}`;
+      return `${col} LIKE ${bindLike(params, likePattern("starts", val))}`;
     case "$endsWith":
-      return `${col} LIKE ${bind(params, `%${String(val)}`)}`;
+      return `${col} LIKE ${bindLike(params, likePattern("ends", val))}`;
     case "$null":
       return val ? `${col} IS NULL` : `${col} IS NOT NULL`;
     case "$exists":
       return val ? `${col} IS NOT NULL` : `${col} IS NULL`;
     default:
-      throw new Error(`[read-scope-sql] unsupported operator "${op}" on "${field}" (fail-closed).`);
+      throw readScopeCompileError(`[read-scope-sql] unsupported operator "${op}" on "${field}" (fail-closed).`);
   }
 }
+function nullValueSatisfiesOperator2(op, value) {
+  switch (op) {
+    // `$eq: null` IS the null predicate; any other comparand is a value test.
+    case "$eq":
+      return value === null;
+    // Mirror image: `$ne: null` compiles to `IS NOT NULL`, which a NULL fails.
+    case "$ne":
+      return value !== null;
+    // Truthiness, matching this file's emitter (see the note above).
+    case "$null":
+      return Boolean(value);
+    case "$exists":
+      return !value;
+    // Negative-polarity set / substring tests hold vacuously for an absent value.
+    case "$nin":
+      return true;
+    // `$notContains` is the one operator where the two JS backends disagree for
+    // a null-valued field (`driver-memory` answers false, `formula` true).
+    // `formula` is followed because `driver-sql` follows it, so this compiler
+    // does not cast a vote on a disagreement that is filed elsewhere.
+    case "$notContains":
+      return true;
+    default:
+      return false;
+  }
+}
+function operatorIsNullTotal2(op, value) {
+  switch (op) {
+    // Compile to `IS NULL` / `IS NOT NULL` — two-valued by construction.
+    case "$null":
+    case "$exists":
+      return true;
+    // A null comparand makes these null PREDICATES too, not comparisons.
+    case "$eq":
+    case "$ne":
+      return value === null;
+    default:
+      return false;
+  }
+}
+function nullGuardForFieldSpec2(spec) {
+  if (spec === null) return "none";
+  if (typeof spec !== "object" || spec instanceof Date || Array.isArray(spec)) return "requireValue";
+  const entries = Object.entries(spec);
+  if (entries.length === 0) return "none";
+  let total = true;
+  let nullSatisfies = true;
+  for (const [op, value] of entries) {
+    if (!operatorIsNullTotal2(op, value)) total = false;
+    if (!nullValueSatisfiesOperator2(op, value)) nullSatisfies = false;
+  }
+  if (total) return "none";
+  return nullSatisfies ? "allowNull" : "requireValue";
+}
+function nullSafeNegationOperand2(node) {
+  const out = {};
+  const guarded = [];
+  for (const [key, value] of Object.entries(node)) {
+    if ((key === "$and" || key === "$or") && Array.isArray(value)) {
+      out[key] = value.map((element) => isFilterNode(element) ? nullSafeNegationOperand2(element) : element);
+      continue;
+    }
+    if (key.startsWith("$")) {
+      out[key] = value;
+      continue;
+    }
+    const guard = nullGuardForFieldSpec2(value);
+    if (guard === "none") {
+      out[key] = value;
+    } else if (guard === "requireValue") {
+      guarded.push({ [key]: { $null: false } }, { [key]: value });
+    } else {
+      guarded.push({ $or: [{ [key]: { $null: true } }, { [key]: value }] });
+    }
+  }
+  if (guarded.length > 0) {
+    const existing = Array.isArray(out.$and) ? out.$and : [];
+    out.$and = [...existing, ...guarded];
+  }
+  return out;
+}
+
+// src/dataset-refusal.ts
+var DATASET_INVALID = "DATASET_INVALID";
+var INVALID_FIELD = "INVALID_FIELD";
+function datasetInvalidError(message) {
+  const err = new Error(message);
+  err.code = DATASET_INVALID;
+  err.status = 400;
+  return err;
+}
+function invalidMemberError(message, meta) {
+  const err = new Error(message);
+  err.code = INVALID_FIELD;
+  err.status = 400;
+  err.member = meta.member;
+  if (meta.param) err.param = meta.param;
+  if (meta.cube) err.cube = meta.cube;
+  return err;
+}
 
 // src/strategies/native-sql-strategy.ts
 var import_core = require("@objectstack/core");
@@ -509,7 +851,7 @@ var NativeSQLStrategy = class {
     if (allowed) {
       for (const alias of joins.keys()) {
         if (!allowed.has(alias)) {
-          throw new Error(
+          throw datasetInvalidError(
             `[NativeSQLStrategy] join "${alias}" is not backed by a declared relationship on cube "${query.cube}". v1 only joins along relationships listed in the dataset's \`include\`.`
           );
         }
@@ -660,8 +1002,9 @@ var NativeSQLStrategy = class {
     const measure = this.lookupMember(cube, member, "measure");
     if (!measure) {
       const declared = Object.keys(cube.measures ?? {});
-      throw new Error(
-        `[native-sql-strategy] cube "${cube.name}" declares no measure "${member}"` + (declared.length ? ` (declared: ${declared.join(", ")})` : " (it declares none)")
+      throw invalidMemberError(
+        `[native-sql-strategy] cube "${cube.name}" declares no measure "${member}"` + (declared.length ? ` (declared: ${declared.join(", ")})` : " (it declares none)"),
+        { member, param: "measures", cube: cube.name }
       );
     }
     const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
@@ -712,16 +1055,24 @@ var NativeSQLStrategy = class {
    * driver-backed `coerceTemporalFilterValue` hook (single source of truth for
    * the date/datetime storage convention — see StrategyContext); when the hook
    * is absent, or returns the value unchanged (the field is not a temporal
-   * column, or the dialect stores it as a native timestamp), falls back to the
-   * generic boolean/number recovery so non-temporal typed columns still bind
-   * correctly.
+   * column, or the dialect stores it as a native timestamp), falls back to
+   * {@link toSqlBindValue} so an unbindable JS type still reaches the driver as
+   * something it can bind.
+   *
+   * [#5526] `value` is `unknown`, not `string`, because a leaf now carries the
+   * author's comparand at its own type. Both halves of this method were already
+   * `unknown`-typed for it: the hook's contract is
+   * `coerceTemporalFilterValue(object, field, value: unknown)` and the fallback
+   * converts only what a driver cannot bind. What CHANGED is that a string is no
+   * longer re-typed on the way out — the fallback used to be
+   * `coerceFilterValueForSql`, which read `'007'` as the integer `7`.
    */
   coerceTemporal(ctx, target, value) {
     if (typeof ctx.coerceTemporalFilterValue === "function") {
       const coerced = ctx.coerceTemporalFilterValue(target.object, target.field, value);
       if (coerced !== value) return coerced;
     }
-    return coerceFilterValueForSql(value);
+    return toSqlBindValue(value);
   }
   /**
    * The column side of {@link coerceTemporal}: normalise the reference so it
@@ -752,9 +1103,31 @@ var NativeSQLStrategy = class {
    * does bind tighter than `OR`, so `a AND b OR c` happens to be right, but
    * being right by construction is what keeps a future edit from making it
    * wrong.
+   *
+   * # `null` is the constant TRUE, and TRUE absorbs a disjunction (#5325)
+   *
+   * A `null` return means "constrains nothing", which is the boolean TRUE — the
+   * AND identity, so it drops out of an `and`, but the OR ABSORBER, so one TRUE
+   * disjunct makes the whole `or` TRUE. Filtering it out of an `or` narrowed the
+   * query to the surviving branches. `NOT TRUE ≡ FALSE`, so a negation whose
+   * operand constrains nothing compiles to the FALSE constant rather than
+   * disappearing (which added no `WHERE` and charted every row).
+   *
+   * # The invariant that keeps `params` aligned
+   *
+   * **A call that returns `null` leaves `params` exactly as it found it.** It
+   * has to: a value bound with no `$n` to consume it shifts every later
+   * placeholder onto the wrong value, and a filter that binds the WRONG comparand
+   * is worse than one that is merely too wide (#5297). Leaves decide emptiness
+   * before they bind, and the absorbing `or` — the one place a clause that HAS
+   * bound is discarded — truncates back to the length it started at, so the
+   * invariant holds inductively for every node kind.
    */
   compileFilterNode(node, cube, parentTable, joins, params, ctx) {
     if (!node) return null;
+    if (node.kind === "const") {
+      return node.value ? SQL_CONST_TRUE : SQL_CONST_FALSE;
+    }
     if (node.kind === "leaf") {
       const colExpr = this.resolveFieldSql(cube, node.member, parentTable, joins);
       const target = this.resolveStorageTarget(cube, node.member, parentTable);
@@ -762,9 +1135,22 @@ var NativeSQLStrategy = class {
     }
     if (node.kind === "not") {
       const inner = this.compileFilterNode(node.child, cube, parentTable, joins, params, ctx);
-      return inner ? `NOT (${inner})` : null;
+      return inner ? `NOT (${inner})` : SQL_CONST_FALSE;
+    }
+    const paramBase = params.length;
+    const joinBase = new Map(joins);
+    const parts = [];
+    for (const child of node.children) {
+      const clause = this.compileFilterNode(child, cube, parentTable, joins, params, ctx);
+      if (clause === null) {
+        if (node.kind !== "or") continue;
+        params.length = paramBase;
+        joins.clear();
+        for (const [alias, clauseSql] of joinBase) joins.set(alias, clauseSql);
+        return null;
+      }
+      parts.push(clause);
     }
-    const parts = node.children.map((child) => this.compileFilterNode(child, cube, parentTable, joins, params, ctx)).filter((s) => !!s);
     if (parts.length === 0) return null;
     if (parts.length === 1) return parts[0];
     return `(${parts.join(node.kind === "or" ? " OR " : " AND ")})`;
@@ -782,11 +1168,11 @@ var NativeSQLStrategy = class {
       startsWith: "LIKE",
       endsWith: "LIKE"
     };
-    const likePattern = {
-      contains: (v) => `%${v}%`,
-      notContains: (v) => `%${v}%`,
-      startsWith: (v) => `${v}%`,
-      endsWith: (v) => `%${v}`
+    const likeShape = {
+      contains: "contains",
+      notContains: "contains",
+      startsWith: "starts",
+      endsWith: "ends"
     };
     if (operator === "set") return `${rawCol} IS NOT NULL`;
     if (operator === "notSet") return `${rawCol} IS NULL`;
@@ -800,10 +1186,12 @@ var NativeSQLStrategy = class {
     }
     const sqlOp = opMap[operator];
     if (!sqlOp || !values || values.length === 0) return null;
-    const pattern = likePattern[operator];
-    if (pattern) {
-      params.push(pattern(values[0]));
-      return `${rawCol} ${sqlOp} $${params.length}`;
+    const shape = likeShape[operator];
+    if (shape) {
+      params.push(likePattern(shape, values[0]));
+      const patternRef = `$${params.length}`;
+      params.push(LIKE_ESCAPE_CHAR);
+      return `${rawCol} ${sqlOp} ${patternRef} ESCAPE $${params.length}`;
     }
     if (operator === "lte") {
       const nextDay = (0, import_core.nextUtcCalendarDay)(values[0]);
@@ -902,6 +1290,12 @@ var SCALAR_SQL_OPS = {
   lt: "<",
   lte: "<="
 };
+var LIKE_SQL_OPS = {
+  contains: { sql: "LIKE", shape: "contains" },
+  notContains: { sql: "NOT LIKE", shape: "contains" },
+  startsWith: { sql: "LIKE", shape: "starts" },
+  endsWith: { sql: "LIKE", shape: "ends" }
+};
 var ObjectQLStrategy = class {
   constructor() {
     this.name = "ObjectQLStrategy";
@@ -1145,6 +1539,17 @@ var ObjectQLStrategy = class {
    * cannot be merged). A loud error beats the silent mis-bucket #3654 kills.
    * `generateSql()` calls this too, so the preview accepts/rejects the same set.
    *
+   * [#5716] All four refusals below are `invalidMemberError` — `INVALID_FIELD` /
+   * 400, naming the member — and the MESSAGES are unchanged (they are good
+   * diagnostics, and #5923's tests read them). Each is decided by two caller-side
+   * facts and nothing else: a member the query named, and whether that member
+   * resolves across a join. Neither is an internal invariant — a cube where the
+   * member exists and a driver that could serve it are both perfectly ordinary,
+   * which is exactly what the "run this on a native-SQL driver" half of each
+   * message says. They are member-level rather than dataset-level (hence not
+   * `datasetInvalidError`) because the fix is always to change or drop ONE named
+   * member, and because they fire on `/analytics/query` where no dataset exists.
+   *
    * Detection is on RESOLVED field names, so a dotted dimension the cube
    * flattens to a real column is treated as base, not cross-object.
    */
@@ -1153,18 +1558,30 @@ var ObjectQLStrategy = class {
     for (const td of query.timeDimensions ?? []) {
       const field = this.resolveFieldName(cube, td.dimension, "dimension");
       if (this.isCrossObjectField(cube, field, baseObject)) {
-        throw new Error(
-          `[Analytics] ObjectQLStrategy cannot bucket a cross-object time dimension ("${field}").`
+        throw invalidMemberError(
+          `[Analytics] ObjectQLStrategy cannot bucket a cross-object time dimension ("${field}").`,
+          { member: td.dimension, param: "timeDimensions", cube: cube.name }
         );
       }
     }
     const nonDim = [
-      ...(query.measures ?? []).map((m) => ({ where: "measure", field: this.resolveMeasureAggregation(cube, m).field })),
-      ...Object.keys(filter).map((f) => ({ where: "filter", field: f }))
+      ...(query.measures ?? []).map((m) => ({
+        where: "measure",
+        member: m,
+        field: this.resolveMeasureAggregation(cube, m).field
+      })),
+      ...Object.keys(filter).map((f) => ({ where: "filter", member: f, field: f }))
     ].filter((r) => this.isCrossObjectField(cube, r.field, baseObject));
     if (nonDim.length > 0) {
-      throw new Error(
-        `[Analytics] ObjectQLStrategy cannot evaluate a cross-object ${nonDim[0].where} ("${nonDim[0].field}") \u2014 the engine cannot join in an aggregate. Run this query on a native-SQL driver, or remove the cross-object ${nonDim[0].where}.`
+      throw invalidMemberError(
+        `[Analytics] ObjectQLStrategy cannot evaluate a cross-object ${nonDim[0].where} ("${nonDim[0].field}") \u2014 the engine cannot join in an aggregate. Run this query on a native-SQL driver, or remove the cross-object ${nonDim[0].where}.`,
+        {
+          member: nonDim[0].member,
+          // The two kinds share one throw, so the request key follows the kind
+          // rather than being guessed by the reader of the message.
+          param: nonDim[0].where === "measure" ? "measures" : "where",
+          cube: cube.name
+        }
       );
     }
     const crossDims = [];
@@ -1174,8 +1591,9 @@ var ObjectQLStrategy = class {
       const [alias, ...rest] = field.split(".");
       const attr = rest.join(".");
       if (attr.includes(".")) {
-        throw new Error(
-          `[Analytics] ObjectQLStrategy supports only single-hop cross-object dimensions; "${field}" traverses more than one relationship.`
+        throw invalidMemberError(
+          `[Analytics] ObjectQLStrategy supports only single-hop cross-object dimensions; "${field}" traverses more than one relationship.`,
+          { member: dim, param: "dimensions", cube: cube.name }
         );
       }
       crossDims.push({ outputName: dim, fkField: alias, attr, refObject: cube.joins?.[alias]?.name ?? alias });
@@ -1184,8 +1602,9 @@ var ObjectQLStrategy = class {
     for (const m of query.measures ?? []) {
       const { method } = this.resolveMeasureAggregation(cube, m);
       if (!RECOMBINABLE_METHODS.has(method)) {
-        throw new Error(
-          `[Analytics] ObjectQLStrategy cannot group by a cross-object dimension with a "${method}" measure ("${m}") \u2014 its value cannot be recombined across the intermediate FK grouping. Use sum/count/min/max, or run on a native-SQL driver.`
+        throw invalidMemberError(
+          `[Analytics] ObjectQLStrategy cannot group by a cross-object dimension with a "${method}" measure ("${m}") \u2014 its value cannot be recombined across the intermediate FK grouping. Use sum/count/min/max, or run on a native-SQL driver.`,
+          { member: m, param: "measures", cube: cube.name }
         );
       }
     }
@@ -1284,10 +1703,21 @@ var ObjectQLStrategy = class {
    * Render one normalized filter as a display SQL predicate for `generateSql`.
    *
    * Mirrors `NativeSQLStrategy.buildFilterClause`'s operator vocabulary so the
-   * two previews read alike, but binds through `coerceFilterValueForObjectQL`:
-   * the comparand shown is the one THIS path actually hands the engine (a real
-   * boolean, not SQL's 1/0). Returns null for an operator/value combination
-   * that carries no predicate, matching `execute()`, which drops it too.
+   * two previews read alike, but binds the comparand VERBATIM: the value shown is
+   * the one THIS path actually hands the engine (a real boolean, not SQL's 1/0).
+   *
+   * [#5526] "Verbatim" is now literal. This used to bind through
+   * `coerceFilterValueForObjectQL`, which decoded the string a `string[]` leaf
+   * carried back into a type — so an echo could show `7` for a filter the author
+   * wrote as `'007'`. A leaf carries the author's value at its own type, so the
+   * echo needs no conversion at all to stay honest about execution. The LIKE
+   * family is still the one exception, for the reason `filter.zod.ts` gives: its
+   * comparand is declared a `string`, and what binds is the PATTERN.
+   *
+   * `null` means "this leaf carries no predicate" — a value-less scalar leaf,
+   * which `execute()` and `NativeSQLStrategy` drop too. It does NOT mean "I could
+   * not render that operator": #5333 was exactly that conflation, and an
+   * unrenderable operator now THROWS (see the exit below).
    */
   buildFilterClauseSql(col, operator, values, params) {
     if (operator === "set") return `${col} IS NOT NULL`;
@@ -1295,18 +1725,25 @@ var ObjectQLStrategy = class {
     if (!values || values.length === 0) return null;
     if (operator === "in" || operator === "notIn") {
       const placeholders = values.map((v) => {
-        params.push(coerceFilterValueForObjectQL(v));
+        params.push(v);
         return `$${params.length}`;
       }).join(", ");
       return `${col} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
     }
-    if (operator === "contains" || operator === "notContains") {
-      params.push(`%${values[0]}%`);
-      return `${col} ${operator === "contains" ? "LIKE" : "NOT LIKE"} $${params.length}`;
+    const like = LIKE_SQL_OPS[operator];
+    if (like) {
+      params.push(likePattern(like.shape, values[0]));
+      const patternRef = `$${params.length}`;
+      params.push(LIKE_ESCAPE_CHAR);
+      return `${col} ${like.sql} ${patternRef} ESCAPE $${params.length}`;
     }
     const op = SCALAR_SQL_OPS[operator];
-    if (!op) return null;
-    params.push(coerceFilterValueForObjectQL(values[0]));
+    if (!op) {
+      throw new Error(
+        `[analytics] ObjectQLStrategy cannot render display SQL for filter operator "${operator}" (on "${col}"). The analytics operator vocabulary is closed \u2014 filter-normalizer.ts refuses anything it cannot map \u2014 so this means a new operator reached the normalizer without an arm here. Add one rather than dropping the predicate: an echo without it describes a WIDER query than the one that ran (#5333).`
+      );
+    }
+    params.push(values[0]);
     return `${col} ${op} $${params.length}`;
   }
   /**
@@ -1418,16 +1855,30 @@ var ObjectQLStrategy = class {
     const rendered = this.filterNodeToCondition(node, cube);
     if (rendered) conjuncts.push(rendered);
   }
-  /** A node as a standalone `FilterCondition` the engine can consume. */
+  /**
+   * A node as a standalone `FilterCondition` the engine can consume.
+   *
+   * `null` = no constraint, which is the boolean TRUE — the AND identity but the
+   * OR ABSORBER, so a `null` branch makes the whole disjunction unconstrained
+   * instead of collapsing it to its surviving branches (#5325). FALSE is handed
+   * to the engine as `{$not: {}}`, the spelling `driver-sql`, `formula` and
+   * `driver-memory`'s matcher all already pin as the zero-row filter (#5134) —
+   * this strategy invents no second one.
+   */
   filterNodeToCondition(node, cube) {
     if (!node) return null;
+    if (node.kind === "const") {
+      return node.value ? null : { $not: {} };
+    }
     if (node.kind === "not") {
       const inner = this.filterNodeToCondition(node.child, cube);
-      return inner ? { $not: inner } : null;
+      return inner ? { $not: inner } : { $not: {} };
     }
     if (node.kind === "or") {
-      const branches = node.children.map((child) => this.filterNodeToCondition(child, cube)).filter((c) => !!c);
-      return branches.length > 0 ? { $or: branches } : null;
+      const branches = node.children.map((child) => this.filterNodeToCondition(child, cube));
+      if (branches.some((c) => c === null)) return null;
+      const kept = branches.filter((c) => !!c);
+      return kept.length > 0 ? { $or: kept } : null;
     }
     const filter = {};
     const conjuncts = [];
@@ -1441,9 +1892,20 @@ var ObjectQLStrategy = class {
    * Render a normalized filter node as the display SQL `/analytics/sql`
    * echoes. Values still bind as `$n` placeholders — the echo travels to the
    * browser, so a comparand is never inlined.
+   *
+   * The boolean identities render too (#5325). This string exists to REPRODUCE
+   * execution: a `{$not: {}}` filter that runs as zero rows but echoes SQL with
+   * no `WHERE` hands whoever is debugging "why is this chart empty" a statement
+   * that returns the whole table. Same reason the absorbed `$or` branch and the
+   * `params` truncation below match {@link NativeSQLStrategy.compileFilterNode}
+   * exactly — including the invariant that a `null` return leaves `params`
+   * untouched, so no comparand is left with no placeholder to consume it.
    */
   renderFilterNodeSql(node, cube, params) {
     if (!node) return null;
+    if (node.kind === "const") {
+      return node.value ? SQL_CONST_TRUE : SQL_CONST_FALSE;
+    }
     if (node.kind === "leaf") {
       return this.buildFilterClauseSql(
         this.resolveFieldName(cube, node.member, "any"),
@@ -1454,9 +1916,19 @@ var ObjectQLStrategy = class {
     }
     if (node.kind === "not") {
       const inner = this.renderFilterNodeSql(node.child, cube, params);
-      return inner ? `NOT (${inner})` : null;
+      return inner ? `NOT (${inner})` : SQL_CONST_FALSE;
+    }
+    const paramBase = params.length;
+    const parts = [];
+    for (const child of node.children) {
+      const clause = this.renderFilterNodeSql(child, cube, params);
+      if (clause === null) {
+        if (node.kind !== "or") continue;
+        params.length = paramBase;
+        return null;
+      }
+      parts.push(clause);
     }
-    const parts = node.children.map((child) => this.renderFilterNodeSql(child, cube, params)).filter((s) => !!s);
     if (parts.length === 0) return null;
     if (parts.length === 1) return parts[0];
     return `(${parts.join(node.kind === "or" ? " OR " : " AND ")})`;
@@ -1492,9 +1964,16 @@ var ObjectQLStrategy = class {
    * performs the same half-open translation itself because it binds into raw
    * SQL, so one dashboard reads the same on every driver.
    *
-   * Comparands are coerced by the SAME helper the `where` path uses, so an
-   * epoch-ms bound recovers as a number and an ISO string stays a string. No
-   * STORAGE coercion happens here, deliberately: `NativeSQLStrategy` needs
+   * [#5526] Bounds are forwarded at the type `dateRange` is DECLARED with —
+   * `string` (`AnalyticsQuerySchema`'s `timeDimensions[].dateRange: string[]`) —
+   * and nothing re-types them. They used to pass through
+   * `coerceFilterValueForObjectQL`, whose TSDoc advertised that "an epoch-ms
+   * bound recovers as a number"; that was a lenient CONSUMER rescuing a shape the
+   * contract does not declare, and the same guess is what read a `'007'` filter
+   * comparand as `7` (Prime Directive #12 — the producer or the spec is where an
+   * epoch-ms window would have to be declared, not here). An author who wants an
+   * instant window writes it as one; a declared `string` binds as a string. No
+   * STORAGE coercion happens here either, deliberately: `NativeSQLStrategy` needs
    * `coerceTemporal` because it binds into raw SQL and had to learn that a
    * SQLite `Field.datetime` is an INTEGER epoch (#2034); this path goes through
    * `engine.aggregate()`, where the driver's own CRUD filter coercion applies —
@@ -1521,20 +2000,34 @@ var ObjectQLStrategy = class {
       if (start == null) continue;
       out.push({
         field: this.resolveFieldName(cube, td.dimension, "dimension"),
-        bounds: {
-          $gte: coerceFilterValueForObjectQL(String(start)),
-          $lte: coerceFilterValueForObjectQL(String(end))
-        }
+        bounds: { $gte: start, $lte: end }
       });
     }
     return out;
   }
+  /**
+   * One leaf as the operand the engine's `FilterCondition` expects.
+   *
+   * [#5526] The comparand is passed through UNCONVERTED. That is the whole of
+   * this path's share of the fix: the engine compares against the value as
+   * STORED, and a leaf now carries the value the author wrote, so `'007'` stays
+   * `'007'`, `true` stays `true` and `7` stays `7` with nothing in between to
+   * re-type them. The two `coerceFilterValueForObjectQL` calls this replaced
+   * existed only to undo `stringifyForCube`, and undoing it required guessing.
+   *
+   * The four LIKE-family arms are the exception, and a contract one:
+   * `filter.zod.ts` declares `$contains` / `$notContains` / `$startsWith` /
+   * `$endsWith` as `z.string()`, so this PRODUCER must hand the engine a real
+   * string — `String(…)`, the same normalisation `like-pattern.ts` applies at the
+   * two SQL emitters and `driver-sql`'s `applyLike` applies at the driver, so one
+   * `$contains` means one thing on every face (#5567's invariant).
+   */
   convertFilter(operator, values) {
     if (operator === "set") return { $ne: null };
     if (operator === "notSet") return null;
     if (!values || values.length === 0) return void 0;
-    const v0 = coerceFilterValueForObjectQL(values[0]);
-    const all = values.map(coerceFilterValueForObjectQL);
+    const v0 = values[0];
+    const all = [...values];
     switch (operator) {
       case "equals":
         return v0;
@@ -1548,19 +2041,42 @@ var ObjectQLStrategy = class {
         return { $lt: v0 };
       case "lte":
         return { $lte: v0 };
+      // [#5557] `contains` was `{ $regex: values[0] }` — the comparand dropped
+      // VERBATIM into a regex position while its three siblings below already
+      // passed as canonical spec operators. Three things were wrong with that,
+      // and none of them waits on #4706's ruling about what `$regex` should
+      // mean:
+      //
+      //   1. `$regex` is not in `filter.zod.ts`'s `FILTER_OPERATORS`, so this
+      //      was a PRODUCER emitting an operator the contract does not declare
+      //      (Prime Directive #12 — fix the producer, not the consumers).
+      //   2. `compileScopedFilterToSql` in this very package is a
+      //      `FilterCondition` consumer and fails closed on `$regex`, so one
+      //      filter tree no longer travelled between two consumers of the same
+      //      contract sitting in the same directory.
+      //   3. On a backend that reads `$regex` as a real regex — driver-memory's
+      //      `memory-matcher.ts` does, deliberately, for plugin-auth's adapter
+      //      — an unescaped comparand changes what the author asked for:
+      //      `a.b` also matched `axb`, and `50% (+)` did not compile at all, so
+      //      the `catch { return false }` answered zero rows in silence.
+      //      `driver-sql` meanwhile compiles `$regex` to a substring LIKE, so
+      //      the same widget returned different row sets per driver.
+      //
+      // `MONGO_TO_CUBE_OP` maps `$contains` → `contains` and nothing else does,
+      // so returning `$contains` here is the round trip of the author's own key.
       case "contains":
-        return { $regex: values[0] };
+        return { $contains: String(v0) };
       // `notContains` had no arm and fell to the `default` below, which returns
       // a BARE VALUE — i.e. `{field: 'x'}`, an equality. "does not contain x"
       // was compiled as "equals x". These three pass through as the canonical
       // spec operators every driver implements directly, so an anchored match
       // stays anchored rather than depending on regex dialect (#4128).
       case "notContains":
-        return { $notContains: values[0] };
+        return { $notContains: String(v0) };
       case "startsWith":
-        return { $startsWith: values[0] };
+        return { $startsWith: String(v0) };
       case "endsWith":
-        return { $endsWith: values[0] };
+        return { $endsWith: String(v0) };
       case "in":
         return { $in: all };
       case "notIn":
@@ -1615,15 +2131,15 @@ var ObjectQLStrategy = class {
 };
 
 // src/dataset-compiler.ts
-var import_data = require("@objectstack/spec/data");
+var import_data2 = require("@objectstack/spec/data");
 var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set(["array_agg", "string_agg"]);
-var SUPPORTED_AGGREGATES = import_data.AggregationFunction.options.filter((a) => !UNSUPPORTED_AGGREGATES.has(a));
+var SUPPORTED_AGGREGATES = import_data2.AggregationFunction.options.filter((a) => !UNSUPPORTED_AGGREGATES.has(a));
 function aggregateToMetricType(m) {
   if (!m.aggregate) {
     throw new Error(`[dataset-compiler] non-derived measure "${m.name}" has no aggregate`);
   }
   if (UNSUPPORTED_AGGREGATES.has(m.aggregate)) {
-    throw new Error(
+    throw datasetInvalidError(
       `[dataset-compiler] measure "${m.name}" uses aggregate "${m.aggregate}" which is not supported by the v1 dataset runtime (supported: ${SUPPORTED_AGGREGATES.join(", ")}).`
     );
   }
@@ -1651,13 +2167,31 @@ function fieldRelationshipPath(field) {
 }
 var MAX_JOIN_HOPS = 3;
 var joinAlias = (path) => path.replace(/\./g, "__");
-function compileDataset(dataset, resolver) {
+function compileDataset(dataset, resolver, options) {
   const include = dataset.include ?? [];
+  const declaredDatasource = (objectName) => {
+    const declared = options?.getObjectDatasource?.(objectName);
+    return declared && declared.toLowerCase() !== "default" ? declared : void 0;
+  };
+  const isExternal = (objectName) => options?.isExternalObject?.(objectName) ?? false;
+  const baseDatasource = declaredDatasource(dataset.object);
+  const sameDatasource = (a, b) => a.toLowerCase() === b.toLowerCase();
+  const baseIsFederated = isExternal(dataset.object);
+  const assertSameDatasource = (targetObject, path) => {
+    if (!baseDatasource || baseIsFederated) return;
+    if (isExternal(targetObject)) return;
+    const targetDatasource = declaredDatasource(targetObject);
+    if (!targetDatasource) return;
+    if (sameDatasource(targetDatasource, baseDatasource)) return;
+    throw datasetInvalidError(
+      `[dataset-compiler] dataset "${dataset.name}" declares a JOIN that crosses datasources: its base object "${dataset.object}" is on datasource "${baseDatasource}", but the joined object "${targetObject}" \u2014 reached via the \`include\` path "${path}" \u2014 is on datasource "${targetDatasource}". A dataset JOIN cannot cross datasources: the whole dataset is executed as ONE statement on the base object's datasource, so "${targetObject}" is simply not there. Fix it by binding both objects to the same datasource, or by dropping "${path}" from the dataset's \`include\` (and every dimension/measure that references it).`
+    );
+  };
   const resolveHop = (fromObject, rel) => {
     if (!resolver) return { object: rel, table: rel };
     const resolved = resolver(fromObject, rel);
     if (!resolved) {
-      throw new Error(
+      throw datasetInvalidError(
         `[dataset-compiler] dataset "${dataset.name}" includes relationship "${rel}" which does not exist on object "${fromObject}".`
       );
     }
@@ -1667,7 +2201,7 @@ function compileDataset(dataset, resolver) {
   for (const path of include) {
     const segments = path.split(".");
     if (segments.length > MAX_JOIN_HOPS) {
-      throw new Error(
+      throw datasetInvalidError(
         `[dataset-compiler] dataset "${dataset.name}" include path "${path}" exceeds the ${MAX_JOIN_HOPS}-hop limit (${segments.length} hops). Deeper traversal is not supported.`
       );
     }
@@ -1677,6 +2211,7 @@ function compileDataset(dataset, resolver) {
     for (const seg of segments) {
       prefix = prefix ? `${prefix}.${seg}` : seg;
       const target = resolveHop(fromObject, seg);
+      assertSameDatasource(target.object, prefix);
       const alias = joinAlias(prefix);
       if (!joins[alias]) {
         joins[alias] = {
@@ -1693,7 +2228,7 @@ function compileDataset(dataset, resolver) {
   const assertDeclared = (field, ownerKind, ownerName) => {
     const relPath = fieldRelationshipPath(field);
     if (relPath && !joins[joinAlias(relPath)]) {
-      throw new Error(
+      throw datasetInvalidError(
         `[dataset-compiler] ${ownerKind} "${ownerName}" references relationship path "${relPath}" via "${field}", but "${relPath}" is not declared in the dataset's \`include\`. Only fields along a declared relationship path are joinable.`
       );
     }
@@ -1751,7 +2286,7 @@ function compileDataset(dataset, resolver) {
 }
 
 // src/dataset-executor.ts
-var import_data2 = require("@objectstack/spec/data");
+var import_data3 = require("@objectstack/spec/data");
 var import_core3 = require("@objectstack/core");
 function resolveSelectionTokens(compiled, selection, context) {
   const tokenCtx = (0, import_core3.filterTokenContextFrom)(context, /* @__PURE__ */ new Date());
@@ -1791,7 +2326,7 @@ function evaluateDerivedMeasures(rows, derived) {
 }
 function fillEmptyGroups(rows, columnAggregates) {
   for (const [column, aggregate2] of Object.entries(columnAggregates)) {
-    const empty = (0, import_data2.emptyGroupValueFor)(aggregate2);
+    const empty = (0, import_data3.emptyGroupValueFor)(aggregate2);
     if (empty === void 0) continue;
     for (const row of rows) if (row[column] == null) row[column] = empty;
   }
@@ -1876,7 +2411,7 @@ function resolveOrdering(selection, dimensions, timeDimensions = []) {
     ]);
     const unknown = Object.keys(order).filter((k) => !selectable.has(k));
     if (unknown.length) {
-      throw new Error(
+      throw datasetInvalidError(
         `[dataset-executor] order key(s) ${unknown.map((k) => `"${k}"`).join(", ")} \u2014 not a selected dimension or measure. Selectable here: ${[...selectable].join(", ") || "(none)"}.`
       );
     }
@@ -1893,7 +2428,9 @@ function resolveOrdering(selection, dimensions, timeDimensions = []) {
 }
 function parseUTC(date) {
   const ms = Date.parse(date.length === 10 ? `${date}T00:00:00Z` : date);
-  if (Number.isNaN(ms)) throw new Error(`[dataset-executor] invalid date in dateRange: "${date}"`);
+  if (Number.isNaN(ms)) {
+    throw datasetInvalidError(`[dataset-executor] invalid date in dateRange: "${date}"`);
+  }
   return ms;
 }
 var DAY_MS = 864e5;
@@ -1905,6 +2442,30 @@ function shiftYear(date, years) {
   d.setUTCFullYear(d.getUTCFullYear() + years);
   return toISODate(d.getTime());
 }
+function resolveCompareDimension(selection) {
+  const cmp = selection.compareTo;
+  const shiftable = (selection.timeDimensions ?? []).filter(
+    (t) => t.dateRange != null
+  );
+  const names = shiftable.map((t) => t.dimension);
+  if (cmp.dimension != null) {
+    if (!names.includes(cmp.dimension)) {
+      throw datasetInvalidError(
+        `[dataset-executor] compareTo requires a timeDimension "${cmp.dimension}" with a dateRange. ` + (names.length > 0 ? `This selection dates ${names.map((n) => `"${n}"`).join(", ")} \u2014 name one of those, or omit compareTo.dimension to let the executor choose when there is only one.` : "This selection declares no timeDimension with a dateRange, so there is no window to shift; give the dimension a dateRange (a dashboard date-range filter is the usual source).")
+      );
+    }
+    return cmp.dimension;
+  }
+  if (names.length === 1) return names[0];
+  if (names.length === 0) {
+    throw datasetInvalidError(
+      "[dataset-executor] compareTo needs a dated window to shift, but this selection declares no timeDimension with a dateRange. Give the time dimension a dateRange (a dashboard date-range filter is the usual source), or drop compareTo \u2014 a period-over-period comparison is only defined against a bounded window."
+    );
+  }
+  throw datasetInvalidError(
+    `[dataset-executor] compareTo.dimension is ambiguous: ${names.length} time dimensions carry a dateRange (${names.map((n) => `"${n}"`).join(", ")}). Name the one to shift \u2014 compareTo: { kind: '${cmp.kind}', dimension: '${names[0]}' }.`
+  );
+}
 function shiftRange(range, kind) {
   const [start, end] = range;
   if (kind === "previousYear") {
@@ -1947,7 +2508,7 @@ var DatasetExecutor = class {
       for (const grouping of groupings) {
         const unknown = grouping.filter((d) => !selected.has(d));
         if (unknown.length) {
-          throw new Error(
+          throw datasetInvalidError(
             `[dataset-executor] totals grouping [${grouping.join(", ")}] is not a subset of the selected dimensions \u2014 unknown: ${unknown.join(", ")}.`
           );
         }
@@ -2056,8 +2617,9 @@ var DatasetExecutor = class {
   async runMeasurePass(compiled, selection, opts) {
     const { measures, dimensions, baseFilter, window, context } = opts;
     const { unfiltered, filtered } = splitMeasuresByFilter(measures, compiled.measureFilters);
+    const primary = unfiltered.length > 0 || filtered.length === 0;
     let result;
-    if (unfiltered.length > 0 || filtered.length === 0) {
+    if (primary) {
       result = await this.service.query(this.buildQuery(compiled, {
         measures: unfiltered,
         dimensions,
@@ -2069,7 +2631,8 @@ var DatasetExecutor = class {
     } else {
       result = { rows: [], fields: [] };
     }
-    for (const m of filtered) {
+    const measureNames = new Set(measures);
+    for (const [i, m] of filtered.entries()) {
       const mFilter = combineFilters(baseFilter, compiled.measureFilters[m]);
       const sub = await this.service.query(this.buildQuery(compiled, {
         measures: [m],
@@ -2079,6 +2642,11 @@ var DatasetExecutor = class {
         contextTimezone: context?.timezone
       }), context);
       result.rows = mergeByDimensions(result.rows, sub.rows, dimensions, [m]);
+      if (!primary && i === 0) {
+        for (const f of sub.fields ?? []) {
+          if (!measureNames.has(f.name)) result.fields.push(f);
+        }
+      }
       result.fields.push({ name: m, type: "number" });
     }
     return result;
@@ -2108,14 +2676,17 @@ var DatasetExecutor = class {
     if (opts.where) q.where = opts.where;
     const selTimeDims = opts.selection.timeDimensions ?? [];
     const selDims = new Set(selTimeDims.map((t) => t.dimension));
+    const groupedDims = new Set(opts.dimensions);
     const granularityFor = (name) => {
       const cd = compiled.cube.dimensions[name];
       if (cd?.type !== "time") return void 0;
       const datasetDefault = cd.granularities?.length === 1 ? String(cd.granularities[0]) : void 0;
       return resolveDimensionGranularity(opts.selection, name, datasetDefault);
     };
+    const bucketsUnstatedEntry = (dimension) => groupedDims.has(dimension) || opts.selection.dateGranularity != null;
     const resolvedTimeDims = selTimeDims.map((t) => {
       if (t.granularity) return t;
+      if (!bucketsUnstatedEntry(t.dimension)) return t;
       const granularity = granularityFor(t.dimension);
       return granularity ? { ...t, granularity } : t;
     });
@@ -2134,16 +2705,12 @@ var DatasetExecutor = class {
   }
   async runCompare(compiled, selection, measures, dimensions, baseFilter, context) {
     const cmp = selection.compareTo;
-    const td = (selection.timeDimensions ?? []).find((t) => t.dimension === cmp.dimension);
-    if (!td || !td.dateRange) {
-      throw new Error(
-        `[dataset-executor] compareTo requires a timeDimension "${cmp.dimension}" with a dateRange.`
-      );
-    }
+    const dimension = resolveCompareDimension(selection);
+    const td = (selection.timeDimensions ?? []).find((t) => t.dimension === dimension);
     const range = Array.isArray(td.dateRange) ? [td.dateRange[0], td.dateRange[1] ?? td.dateRange[0]] : [td.dateRange, td.dateRange];
     const shifted = shiftRange(range, cmp.kind);
     const shiftedTd = (selection.timeDimensions ?? []).map(
-      (t) => t.dimension === cmp.dimension ? { ...t, dateRange: shifted } : t
+      (t) => t.dimension === dimension ? { ...t, dateRange: shifted } : t
     );
     const sub = await this.runMeasurePass(
       compiled,
@@ -2158,8 +2725,22 @@ var DatasetExecutor = class {
     });
   }
 };
+var NULL_DIMENSION_SEGMENT = "~";
+function dimensionKeyOf(row, dimensions) {
+  let key = "";
+  for (const d of dimensions) {
+    const value = row[d];
+    if (value == null) {
+      key += NULL_DIMENSION_SEGMENT;
+      continue;
+    }
+    const s = String(value);
+    key += `${s.length}:${s}`;
+  }
+  return key;
+}
 function mergeByDimensions(base, extra, dimensions, valueColumns) {
-  const keyOf = (row) => dimensions.map((d) => String(row[d] ?? "")).join("
");
+  const keyOf = (row) => dimensionKeyOf(row, dimensions);
   const index = /* @__PURE__ */ new Map();
   for (const row of base) index.set(keyOf(row), row);
   for (const row of extra) {
@@ -2511,15 +3092,71 @@ function evaluateAnalyticsQueryOverRows(query, cube, rows) {
 }
 
 // src/analytics-service.ts
+function hasDeclaredErrorEnvelope(err) {
+  const e = err;
+  return typeof e?.status === "number" && typeof e?.code === "string" && e.code.length > 0;
+}
 function isMissingSourceError(err) {
-  const msg = String(err?.message ?? err ?? "").toLowerCase();
+  const raw = String(err?.message ?? err ?? "");
+  const msg = raw.toLowerCase();
   return msg.includes("no such table") || // sqlite / libsql
-  msg.includes("relation") && msg.includes("does not exist") || // postgres
+  /relation\s+[`"']?[A-Za-z0-9_$.]+[`"']?\s+does not exist/i.test(raw) || // postgres
   msg.includes("doesn't exist") || // mysql ("table ... doesn't exist")
   msg.includes("not registered") || // framework: object not in registry
   msg.includes("unknown object") || msg.includes("is not a registered object");
 }
+function missingSourceRelation(err) {
+  const msg = String(err?.message ?? err ?? "");
+  const patterns = [
+    /no such table:\s*[`"'[]?([A-Za-z0-9_$.]+)/i,
+    // sqlite / libsql
+    /relation\s+[`"']?([A-Za-z0-9_$.]+)[`"']?\s+does not exist/i,
+    // postgres
+    /table\s+[`"']?([A-Za-z0-9_$.]+)[`"']?\s+doesn't exist/i,
+    // mysql
+    /(?:object|table)\s+[`"']([A-Za-z0-9_$.]+)[`"']\s+is not registered/i,
+    // framework
+    /unknown object:?\s*[`"']?([A-Za-z0-9_$.]+)/i,
+    /[`"']([A-Za-z0-9_$.]+)[`"']\s+is not a registered object/i
+  ];
+  for (const re of patterns) {
+    const m = re.exec(msg);
+    if (m?.[1]) {
+      const parts = m[1].split(".").filter(Boolean);
+      const bare = parts[parts.length - 1];
+      if (bare) return bare;
+    }
+  }
+  return void 0;
+}
 var BARE_IDENTIFIER = /^[a-z_][a-z0-9_]*$/i;
+function declaredMemberEntry(cube, member, kind) {
+  const bags = kind === "dimension" ? [cube.dimensions] : [
+    cube.dimensions,
+    cube.measures
+  ];
+  for (const bag of bags) {
+    if (bag[member]) return { ...bag[member], key: member };
+    if (member.includes(".")) {
+      const [first, ...rest] = member.split(".");
+      const tail = rest.join(".");
+      if (first === cube.name && bag[tail]) return { ...bag[tail], key: tail };
+      if (bag[tail]) return { ...bag[tail], key: tail };
+      const flat = member.replace(/\./g, "_");
+      if (bag[flat]) return { ...bag[flat], key: flat };
+    }
+  }
+  return void 0;
+}
+function resolveMemberSource(cube, member, kind) {
+  const entry = declaredMemberEntry(cube, member, kind);
+  if (entry) {
+    const source = typeof entry.sql === "string" ? entry.sql.trim() : "";
+    return { key: entry.key, source: source && BARE_IDENTIFIER.test(source) ? source : null };
+  }
+  if (member.includes(".")) return { key: member, source: null };
+  return { key: member, source: BARE_IDENTIFIER.test(member) ? member : null };
+}
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
   objectqlAggregate: false,
@@ -2543,6 +3180,8 @@ var AnalyticsService = class {
     this.draftRowsResolver = config.draftRowsResolver;
     this.isRegisteredObject = config.isRegisteredObject;
     this.getObjectFieldNames = config.getObjectFieldNames;
+    this.getObjectDatasource = config.getObjectDatasource;
+    this.isExternalObject = config.isExternalObject;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -2679,7 +3318,10 @@ var AnalyticsService = class {
    * compiled dataset.
    */
   registerDataset(dataset) {
-    const compiled = compileDataset(dataset, this.relationshipResolver);
+    const compiled = compileDataset(dataset, this.relationshipResolver, {
+      getObjectDatasource: this.getObjectDatasource,
+      isExternalObject: this.isExternalObject
+    });
     this.cubeRegistry.register(compiled.cube);
     this.datasetRegistry.set(dataset.name, compiled);
     return compiled;
@@ -2723,9 +3365,22 @@ var AnalyticsService = class {
     try {
       result = await new DatasetExecutor(this, orderLabels).execute(compiled, selection, context);
     } catch (err) {
+      if (hasDeclaredErrorEnvelope(err)) throw err;
       if (isMissingSourceError(err)) {
+        const missing = missingSourceRelation(err);
+        const detail = String(err?.message ?? err);
+        const joined = missing && missing.toLowerCase() !== dataset.object.toLowerCase() ? missing : void 0;
+        if (joined && (this.isRegisteredObject?.(joined) ?? true)) {
+          const baseDs = this.getObjectDatasource?.(dataset.object);
+          const joinedDs = this.getObjectDatasource?.(joined);
+          const where = baseDs ? `datasource "${baseDs}"` : "the default datasource";
+          const joinedWhere = joinedDs ? `datasource "${joinedDs}"` : "the default datasource";
+          throw new Error(
+            `[Analytics] dataset "${dataset.name}" cannot be executed as one statement: table "${joined}" is not on ${where}, which is where its base object "${dataset.object}" lives \u2014 "${joined}" is registered on ${joinedWhere}. A dataset JOIN cannot cross datasources. Fix it by binding both objects to the same datasource, or by dropping the cross-datasource relationship from the dataset's \`include\`/dimensions. (driver said: ${detail})`
+          );
+        }
         this.logger.warn(
-          `[Analytics] dataset "${dataset.name}" backing object "${dataset.object}" is unavailable (${String(err?.message ?? err)}); returning an empty result instead of failing the widget`
+          `[Analytics] dataset "${dataset.name}" backing object "${dataset.object}" is unavailable (${detail}); returning an empty result instead of failing the widget`
         );
         return { rows: [], fields: [], totals: [] };
       }
@@ -2818,13 +3473,19 @@ var AnalyticsService = class {
           }
         }
         if (f.percentScale == null) {
-          f.percentScale = m.derived?.op === "ratio" ? "fraction" : (0, import_data3.percentScaleOf)(meta);
+          f.percentScale = m.derived?.op === "ratio" ? "fraction" : (0, import_data4.percentScaleOf)(meta);
         }
       }
     }
-    if (result.fields?.length && selectedDims.length) {
-      const dimByName = new Map(selectedDims.map((d) => [d.name, d]));
-      const dimByField = new Map(selectedDims.filter((d) => !!d.field).map((d) => [d.field, d]));
+    const describableDims = [...selectedDims];
+    for (const t of selection.timeDimensions ?? []) {
+      if (describableDims.some((d2) => d2.name === t.dimension)) continue;
+      const d = dataset.dimensions?.find((x) => x.name === t.dimension);
+      if (d) describableDims.push(d);
+    }
+    if (result.fields?.length && describableDims.length) {
+      const dimByName = new Map(describableDims.map((d) => [d.name, d]));
+      const dimByField = new Map(describableDims.filter((d) => !!d.field).map((d) => [d.field, d]));
       for (const f of result.fields) {
         if (f.label != null) continue;
         const d = dimByName.get(f.name) ?? dimByField.get(f.name);
@@ -2878,6 +3539,19 @@ var AnalyticsService = class {
    *   `cube.measures` (e.g. `amount_sum`, `amount_avg` emitted by dashboard
    *   widget translators), inject suffix-inferred Metric entries so the
    *   strategies pick the right aggregation function and field.
+   *
+   * It is also where the three SOURCE-FIELD gates run, on every path out of this
+   * method and always BEFORE the (possibly augmented) cube is registered:
+   * {@link assertMeasureFields} (#4437), {@link assertDimensionFields} (#5520)
+   * and {@link assertWhereFields} (#5669) — one per request key that can carry a
+   * field name. All three answer the same question — does the object actually
+   * have the column this member resolves to — and all three must answer it here,
+   * because from the strategy onwards the answer is the driver's `no such
+   * column`.
+   *
+   * They run in request-key order (measures → dimensions/timeDimensions →
+   * where), so a query that gets several wrong is answered about one at a time,
+   * naming a real mistake either way.
    */
   ensureCube(query) {
     const name = query.cube;
@@ -2886,6 +3560,8 @@ var AnalyticsService = class {
       this.assertInferableCube(name);
       cube = this.inferCubeFromQuery(query);
       this.assertMeasureFields(query, cube, Object.keys(cube.measures));
+      this.assertDimensionFields(query, cube, Object.keys(cube.dimensions));
+      this.assertWhereFields(query, cube, Object.keys(cube.dimensions));
       this.cubeRegistry.register(cube);
       const isScalarMetric = (query.dimensions?.length ?? 0) === 0 && (query.timeDimensions?.length ?? 0) === 0;
       const message = `[Analytics] No cube registered for "${name}"; auto-inferred a minimal cube (sql="${name}", measures=${Object.keys(cube.measures).join(",") || "(none)"}, dimensions=${Object.keys(cube.dimensions).join(",") || "(none)"}). Define an explicit Cube in your stack for full control.`;
@@ -2906,12 +3582,16 @@ var AnalyticsService = class {
         measures: { ...cube.measures, ...extraMeasures }
       };
       this.assertMeasureFields(query, augmented, Object.keys(cube.measures));
+      this.assertDimensionFields(query, augmented, Object.keys(cube.dimensions));
+      this.assertWhereFields(query, augmented, Object.keys(cube.dimensions));
       this.cubeRegistry.register(augmented);
       this.logger.debug(
         `[Analytics] Augmented cube "${name}" with inferred measures: ${Object.keys(extraMeasures).join(",")}`
       );
     } else {
       this.assertMeasureFields(query, cube, Object.keys(cube.measures));
+      this.assertDimensionFields(query, cube, Object.keys(cube.dimensions));
+      this.assertWhereFields(query, cube, Object.keys(cube.dimensions));
     }
   }
   /**
@@ -2983,6 +3663,207 @@ var AnalyticsService = class {
       throw err;
     }
   }
+  /**
+   * [#5520] Reject a DIMENSION whose source field the backing object does not
+   * have, BEFORE the strategy compiles it into `GROUP BY`.
+   *
+   * The symmetric half of {@link assertMeasureFields}. #4437 closed the measure
+   * side and stopped there, so the identical mistake one request key over still
+   * reached the driver:
+   *
+   * ```
+   * POST /analytics/query {"cube":"crm_account","measures":["account_count"],"dimensions":["bogus_dim"]}
+   * → 500 {"code":"SQLITE_ERROR","message":"Internal server error"}
+   *
+   * POST /analytics/dataset/query {"selection":{"dimensions":["bogus_dim"],…}}
+   * → 500 {"code":"ANALYTICS_QUERY_FAILED",
+   *        "error":"SELECT bogus_dim AS \"bogus_dim\", … GROUP BY bogus_dim - no such column: bogus_dim"}
+   * ```
+   *
+   * A driver error class as the caller's `error.code` is the ADR-0112 violation
+   * #4437 named, and the dataset face additionally echoed the generated
+   * statement — physical table and column names — back to the caller. The
+   * envelope here is deliberately the SAME as the measure gate's
+   * (`INVALID_FIELD`/400 + `field`/`object`/`param`), because "the query names a
+   * field the object does not have" is ONE mistake and must have one wire shape
+   * whichever member kind carried it.
+   *
+   * What it checks, and what it deliberately does not:
+   *
+   * - **Both dimension keys.** `query.dimensions` and `query.timeDimensions`
+   *   land in the same `cube.dimensions` bag, are resolved by the same
+   *   `lookupMember`, and produced the same 500 (a bogus time dimension became
+   *   `date_trunc('month', bogus_at)`); `param` reports which key carried it.
+   * - **An UNDECLARED but real field stays legal.** `dimensions: ['phone']` on a
+   *   cube that never declared `phone` groups by `phone` today — the dimension
+   *   twin of measure auto-inference, and an established contract. So the
+   *   question asked is "does the OBJECT have this field", never "did the cube
+   *   declare this dimension". An undeclared member is checked against the
+   *   object under the name the strategies would use as the column (their own
+   *   `resolveDimensionSql`/`resolveFieldName` fallback: the member itself).
+   * - Only when the cube's `sql` is a bare OBJECT NAME, only when
+   *   {@link AnalyticsServiceConfig.getObjectFieldNames} answers, and only for
+   *   sources that are BARE COLUMNS — same three stand-downs as the measure
+   *   gate, for the same reasons (no field list to check against; nothing
+   *   authoritative to consult; a dotted reference resolves through a join whose
+   *   target this gate cannot see, so it belongs to the join allowlist).
+   * - `id` / `created_at` / `updated_at` are admitted unconditionally, matching
+   *   the data path's `resolveQueryFields`.
+   *
+   * Runs after the measure gate and before the `where` gate on each `ensureCube`
+   * path, so a query that gets several wrong is answered about its measure
+   * first — one rejection at a time, naming a real mistake either way.
+   */
+  assertDimensionFields(query, cube, declaredDimensions) {
+    const probe = this.getObjectFieldNames;
+    if (!probe) return;
+    const members = [
+      ...(query.dimensions ?? []).map((member) => ({ member, param: "dimensions" })),
+      ...(query.timeDimensions ?? []).map((td) => ({ member: td.dimension, param: "timeDimensions" }))
+    ];
+    if (members.length === 0) return;
+    const object = typeof cube.sql === "string" ? cube.sql.trim() : "";
+    if (!object || !BARE_IDENTIFIER.test(object)) return;
+    const fieldNames = probe(object);
+    if (!fieldNames || fieldNames.length === 0) return;
+    const known = /* @__PURE__ */ new Set([...fieldNames, "id", "created_at", "updated_at"]);
+    const resolve = (member) => resolveMemberSource(cube, member, "dimension");
+    const invalid = /* @__PURE__ */ new Set();
+    for (const { member } of members) {
+      const { key, source } = resolve(member);
+      if (source && !known.has(source)) invalid.add(key);
+    }
+    if (invalid.size === 0) return;
+    const usable = declaredDimensions.filter((d) => !invalid.has(d));
+    for (const { member, param } of members) {
+      const { source } = resolve(member);
+      if (!source || known.has(source)) continue;
+      const kind = param === "timeDimensions" ? "Time dimension" : "Dimension";
+      const verb = param === "timeDimensions" ? "buckets" : "groups by";
+      const err = new Error(
+        `${kind} '${member}' on cube '${cube.name}' ${verb} field '${source}', which object '${object}' does not have. Valid dimensions: ${usable.join(", ") || "(none)"}. Any of the object's OWN fields may also be used as a dimension without the cube declaring it, so check the spelling of '${source}' \u2014 known fields: ${[...fieldNames].sort().join(", ")}.`
+      );
+      err.code = "INVALID_FIELD";
+      err.status = 400;
+      err.field = source;
+      err.object = object;
+      err.param = param;
+      err.dimension = member;
+      throw err;
+    }
+  }
+  /**
+   * [#5669] Reject a `where` member whose source field the backing object does
+   * not have, BEFORE the strategy compiles it into `WHERE`.
+   *
+   * The third and last param of one defect. #4437 gated `measures`, #5520 gated
+   * `dimensions`/`timeDimensions`, and the filter face — the request key that
+   * most often carries a hand-typed field name — had no gate at all:
+   *
+   * ```
+   * POST /analytics/query {"cube":"crm_account","measures":["count"],"where":{"bogus_col":"x"}}
+   * → SELECT COUNT(*) AS "count" FROM "crm_account" WHERE bogus_col = $1
+   * → 500 {"code":"SQLITE_ERROR","message":"Internal server error"}
+   * ```
+   *
+   * Same envelope as its two siblings (`INVALID_FIELD`/400 + `field`/`object`/
+   * `param`), because "the query names a field the object does not have" is ONE
+   * mistake whichever request key carried it, and the DATA route has answered it
+   * that way since #4315/#4254 (`resolveQueryFields`).
+   *
+   * # Where the field names come from: the SQL producer's own reader
+   *
+   * The members are collected through `normalizeAnalyticsFilterTree` +
+   * `collectFilterLeaves` — the SAME pair both strategies call to build the
+   * predicate. This is deliberate and is the whole reason this gate is not a
+   * second filter-tree walker: a hand-rolled walk would have to re-derive
+   * `$and`/`$or`/`$not` recursion, `$`-prefixed operator keys, `$between`
+   * lowering, the nested-relation dot flattening (`{owner: {region: 'NA'}}` →
+   * member `owner.region`) and the #5334 array lowering, and every divergence
+   * would show up as "the field the gate saw" not being "the column that reached
+   * SQL" — in either direction (a phantom rejection, or a hole).
+   * `collectFilterLeaves` discards structure, which is exactly right here:
+   * whether a predicate sits under an `$or` changes nothing about whether its
+   * column exists. (Its doc's warning — never rebuild a predicate from this list
+   * — does not apply; this gate builds nothing.)
+   *
+   * # Three stand-downs at query level, plus the per-member ones
+   *
+   * - No {@link AnalyticsServiceConfig.getObjectFieldNames}, cube `sql` that is
+   *   not a bare object name, or a probe that cannot answer for the object — the
+   *   same three tiers as the measure and dimension gates, for the same reasons.
+   * - A `where` the normalizer REFUSES (an unknown operator, a non-array
+   *   `$and`, an unlowerable filter array) is not judged here: this gate stands
+   *   down and lets the refusal happen where it already does. Those inputs
+   *   already answer `INVALID_FILTER`/400 from the strategy (#5352/#5367's
+   *   geography, not this gate's), and pulling them forward into `ensureCube`
+   *   would newly refuse them on the draft-preview path too, whose
+   *   `matchesWhere` never consults the normalizer at all. A field gate that
+   *   cannot read the tree has nothing to say about it.
+   * - Per member, {@link resolveMemberSource} stands down on an expression `sql`
+   *   and on a dotted relation traversal — for the dimension gate's reasons.
+   *
+   * # Array `where` IS gated, and #5353's fix did not change that
+   *
+   * Since #5334 an array `where` is lowered by `normalizeAnalyticsFilterTree`
+   * and compiles to the identical predicate — a measured fact,
+   * `where: [['bogus_col','=','x']]` and `where: {bogus_col: 'x'}` both produce
+   * `WHERE bogus_col = $1` and hand `executeAggregate` the same
+   * `{bogus_col: 'x'}`. Gating one spelling and not the other would answer one
+   * mistake two ways, which is the split this whole gate family exists to close.
+   *
+   * `inferCubeFromQuery` used to skip an array `where` when minting the ad-hoc
+   * cube's `dimensions` — a separate question (the cube's dimension VOCABULARY,
+   * not which columns reach the driver), fixed by #5353 by lowering before
+   * reading keys. Because this gate reads filter LEAVES rather than
+   * `cube.dimensions`, that fix could not change its verdicts, and measurement
+   * confirms it did not: the array where's keys now reach `cube.dimensions`, so
+   * {@link resolveMemberSource} takes the DECLARED-dimension branch for those
+   * members instead of the undeclared-bare-column one — and both branches yield
+   * the same `source` for the same member, since the minted dimension's `sql` IS
+   * the member name. What did change is the rejection's suggestion list, in the
+   * direction that closes the split: `Valid filter members:` now reads the same
+   * for both spellings of one filter.
+   */
+  assertWhereFields(query, cube, declaredDimensions) {
+    const probe = this.getObjectFieldNames;
+    if (!probe) return;
+    const where = query.where;
+    if (!where || typeof where !== "object") return;
+    const object = typeof cube.sql === "string" ? cube.sql.trim() : "";
+    if (!object || !BARE_IDENTIFIER.test(object)) return;
+    const fieldNames = probe(object);
+    if (!fieldNames || fieldNames.length === 0) return;
+    const known = /* @__PURE__ */ new Set([...fieldNames, "id", "created_at", "updated_at"]);
+    let members;
+    try {
+      members = collectFilterLeaves(normalizeAnalyticsFilterTree(query)).map((leaf) => leaf.member);
+    } catch {
+      return;
+    }
+    if (members.length === 0) return;
+    const invalid = /* @__PURE__ */ new Set();
+    for (const member of members) {
+      const { key, source } = resolveMemberSource(cube, member, "any");
+      if (source && !known.has(source)) invalid.add(key);
+    }
+    if (invalid.size === 0) return;
+    const usable = declaredDimensions.filter((d) => !invalid.has(d));
+    for (const member of members) {
+      const { source } = resolveMemberSource(cube, member, "any");
+      if (!source || known.has(source)) continue;
+      const err = new Error(
+        `Filter member '${member}' in 'where' on cube '${cube.name}' constrains field '${source}', which object '${object}' does not have. Valid filter members: ${usable.join(", ") || "(none)"}. Any of the object's OWN fields may also be filtered on without the cube declaring it, so check the spelling of '${source}' \u2014 known fields: ${[...fieldNames].sort().join(", ")}.`
+      );
+      err.code = "INVALID_FIELD";
+      err.status = 400;
+      err.field = source;
+      err.object = object;
+      err.param = "where";
+      err.member = member;
+      throw err;
+    }
+  }
   /**
    * [#3867] Gate on the cube auto-inference path: a name with no registered
    * Cube may only be inferred into one if it is a registered object.
@@ -3021,29 +3902,37 @@ var AnalyticsService = class {
     const cubeName = query.cube;
     const measures = {};
     const dimensions = {};
-    const stripPrefix = (m) => m.includes(".") ? m.split(".").slice(1).join(".") : m;
+    const stripCubeQualifier = (m) => {
+      const dot = m.indexOf(".");
+      if (dot < 0) return m;
+      return m.slice(0, dot) === cubeName ? m.slice(dot + 1) : m;
+    };
     measures.count = { name: "count", label: "Count", type: "count", sql: "*" };
     for (const m of query.measures || []) {
-      const key = stripPrefix(m);
+      const key = m.includes(".") ? m.split(".").slice(1).join(".") : m;
       if (measures[key]) continue;
       const inferred = inferMeasure(key);
       measures[key] = inferred;
     }
     for (const d of query.dimensions || []) {
-      const key = stripPrefix(d);
+      const key = stripCubeQualifier(d);
       if (dimensions[key]) continue;
       dimensions[key] = { name: key, label: key, type: "string", sql: key };
     }
-    if (query.where && typeof query.where === "object" && !Array.isArray(query.where)) {
-      for (const key of Object.keys(query.where)) {
-        if (key.startsWith("$")) continue;
-        const stripped = stripPrefix(key);
-        if (dimensions[stripped] || measures[stripped]) continue;
-        dimensions[stripped] = { name: stripped, label: stripped, type: "string", sql: stripped };
+    let lowered = null;
+    try {
+      lowered = lowerAnalyticsWhere(query);
+    } catch {
+    }
+    if (lowered) {
+      for (const key of conjunctFieldKeys(lowered)) {
+        const minted = stripCubeQualifier(key);
+        if (dimensions[minted] || measures[minted]) continue;
+        dimensions[minted] = { name: minted, label: minted, type: "string", sql: minted };
       }
     }
     for (const td of query.timeDimensions || []) {
-      const key = stripPrefix(td.dimension);
+      const key = stripCubeQualifier(td.dimension);
       if (dimensions[key]) continue;
       dimensions[key] = {
         name: key,
@@ -3210,7 +4099,7 @@ var AnalyticsServicePlugin = class {
           return void 0;
         }
       };
-      executeRawSql = async (_objectName, sql, params) => {
+      executeRawSql = async (objectName, sql, params) => {
         const engine = tryGetExecutor();
         if (!engine || !engine.execute) {
           throw new Error(
@@ -3218,7 +4107,7 @@ var AnalyticsServicePlugin = class {
           );
         }
         const knexSql = sql.replace(/\$(\d+)/g, "?");
-        const result = await engine.execute(knexSql, { args: params });
+        const result = await engine.execute(knexSql, { args: params, object: objectName });
         if (result === null || result === void 0) {
           const err = new Error(
             `[Analytics] The "data" engine's driver returned null for raw SQL \u2014 this driver does not support SQL execution. The query will fall back to an aggregate-based strategy when one is available.`
@@ -3372,6 +4261,12 @@ var AnalyticsServicePlugin = class {
         const f = dataEngine()?.getObject?.(object)?.fields?.[field];
         return f ? { type: f.type, max: f.max, defaultCurrency: f.currencyConfig?.defaultCurrency } : void 0;
       },
+      // #5033 — the datasource an object is bound to, used ONLY to name the
+      // actual cause when a dataset's SQL references a table that is not on the
+      // datasource the query was routed to. Undefined ⇒ the object rides the
+      // default datasource (or the engine cannot answer), and the diagnostic
+      // says so rather than inventing a name.
+      getObjectDatasource: (objectName) => dataEngine()?.getObject?.(objectName)?.datasource,
       // ADR-0062 D6 — a federated object carries an `external` block (ADR-0015).
       // Reported so NativeSQLStrategy declines it (its hand-compiled FROM would
       // hit the wrong physical table) and the driver-correct ObjectQL path runs.
@@ -3393,7 +4288,8 @@ var AnalyticsServicePlugin = class {
         if (!engine) return true;
         return engine.getObject?.(name) != null;
       },
-      // [#4437] Field names for the measure source-field gate. Read from the
+      // [#4437, #5520] Field names for the two source-field gates — measures
+      // (#4437) and dimensions/timeDimensions (#5520). Read from the
       // SAME schema registry `isRegisteredObject` above consults (and the data
       // path's #4315 gate reads), so "which fields exist" has one answer across
       // /data and /analytics. `undefined` — no engine, unknown object, or an