@objectstack/service-analytics 17.0.0 → 17.2.0

package/dist/index.cjs

@@ -41,9 +41,9 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/analytics-service.ts
-var import_data5 = require("@objectstack/spec/data");
+var import_data6 = require("@objectstack/spec/data");
 var import_ui2 = require("@objectstack/spec/ui");
-var import_core5 = require("@objectstack/core");
+var import_core6 = require("@objectstack/core");
 var import_types = require("@objectstack/types");
 
 // src/cube-registry.ts
@@ -162,21 +162,18 @@ var CubeRegistry = class {
 };
 
 // src/strategies/filter-normalizer.ts
-var import_data = require("@objectstack/spec/data");
+var import_data2 = require("@objectstack/spec/data");
 var import_api = require("@objectstack/spec/api");
 
 // src/comparand-shape.ts
+var import_core = require("@objectstack/core");
+var import_data = require("@objectstack/spec/data");
 function isBindableComparand(value) {
-  if (value === null || value === void 0) return true;
-  const kind = typeof value;
-  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
-  return value instanceof Date || ArrayBuffer.isView(value);
+  if (value === void 0) return true;
+  return (0, import_data.isAcceptedFilterComparand)(value) || ArrayBuffer.isView(value);
 }
 function isRenderableTextComparand(value) {
-  if (value === null || value === void 0) return true;
-  const kind = typeof value;
-  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
-  return value instanceof Date;
+  return value === void 0 || (0, import_data.isAcceptedFilterComparand)(value);
 }
 function isFieldReference(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -212,6 +209,51 @@ function findIn(node, field) {
   }
   return null;
 }
+function findUninterpretableTemporalMember(filter, kindOf) {
+  return findUninterpretableIn(filter, "", kindOf);
+}
+function findUninterpretableIn(node, field, kindOf) {
+  if (!node || typeof node !== "object") return null;
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const hit = findUninterpretableIn(child, field, kindOf);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (node instanceof Date || ArrayBuffer.isView(node)) return null;
+  if (isFieldReference(node)) return null;
+  for (const [key, value] of Object.entries(node)) {
+    const scope = key.startsWith("$") ? field : key;
+    const kind = scope ? kindOf(scope) : null;
+    if (kind) {
+      const hit2 = judgeTemporalLiterals(value, scope, kind);
+      if (hit2) return hit2;
+      continue;
+    }
+    const hit = findUninterpretableIn(value, scope, kindOf);
+    if (hit) return hit;
+  }
+  return null;
+}
+function judgeTemporalLiterals(value, field, kind) {
+  if (Array.isArray(value)) {
+    for (const member of value) {
+      const hit = judgeTemporalLiterals(member, field, kind);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (value && typeof value === "object") {
+    if (value instanceof Date || ArrayBuffer.isView(value) || isFieldReference(value)) return null;
+    for (const nested of Object.values(value)) {
+      const hit = judgeTemporalLiterals(nested, field, kind);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  return (0, import_core.isUninterpretableTemporalComparand)(kind, value) ? { field, kind, value } : null;
+}
 var TEXT_PATTERN_OPERATORS = /* @__PURE__ */ new Set([
   "$contains",
   "$notContains",
@@ -229,7 +271,7 @@ function shapePreview(value) {
   }
 }
 function unrenderableTextComparandMessage(op, field, value) {
-  return `"${op}" on "${field}" matches against the TEXT of a pattern, but its comparand is ${Array.isArray(value) ? "an array" : "an object"} (${shapePreview(value)}). filter.zod.ts declares it a string (StringOperatorSchema); a string, number, boolean, null or Date is accepted. Refusing rather than stringifying it: String({}) is "[object Object]", so the pattern that ran would be one nobody wrote \u2014 and a row storing that literal text matches it.`;
+  return `"${op}" on "${field}" matches against the TEXT of a pattern, but its comparand is ${Array.isArray(value) ? "an array" : "an object"} (${shapePreview(value)}). filter.zod.ts declares it a string (StringOperatorSchema); ${import_data.ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} is accepted. Refusing rather than stringifying it: String({}) is "[object Object]", so the pattern that ran would be one nobody wrote \u2014 and a row storing that literal text matches it.`;
 }
 function fieldReferenceComparandMessage(op, field, ref, position) {
   return `"${op}" on "${field}"${position ? ` (${position})` : ""} compares against the field reference { "$field": "${ref}" }, which this compiler does not lower into a column-to-column comparison. Refusing rather than binding it: the reference object used to become the BOUND VALUE of the comparison, so the emitted predicate compared "${field}" against the reference itself \u2014 a value no row can hold \u2014 and a read scope built from it answered the wrong row set with nothing to read. \u26A0\uFE0F This is NOT the platform declining the rule. @objectstack/spec declares this shape (FieldReferenceSchema), @objectstack/formula resolves it per record in memory, driver-sql / driver-sqlite-wasm compile it to a same-table column comparison for the six scalar operators since #5222, and since the 2026-08-12 ruling on #7598 the analytics native-SQL strategy DECLINES such a query so it routes to the ObjectQL engine path and runs there \u2014 the driver enforcing declared-only enumeration, the tenant-isolation ban and the comparison class with metadata it owns. What refuses here is this SQL lowering, whose only remaining caller is the /analytics/sql display echo; it has no faithful rendering of the predicate the engine path actually runs, and half-rendering one would describe a query that returns different rows. Run the query itself (/analytics/query) to get its rows (#7598).`;
@@ -238,7 +280,7 @@ function fieldReferenceBetweenBoundMessage(op, field, ref, index) {
   return `"${op}" on "${field}" has the field reference { "$field": "${ref}" } at index ${index} of its [min, max] bounds. A range BOUND may not be a field reference on any backend: driver-sql and driver-sqlite-wasm refuse both endpoints (#5222), @objectstack/formula does not resolve a reference inside a list either \u2014 it orders the bounds against the raw reference object, which no value compares meaningfully to \u2014 and @objectstack/spec no longer declares the position at all (#7596 removed FieldReferenceSchema from the $between endpoint union, ADR-0049 declared = enforced). Refusing rather than lowering it: this compiler splits $between into its two bounds, so the reference would arrive at the driver under a "$gte" / "$lte" the author never wrote \u2014 a position the SQL drivers DO compile \u2014 and the range would quietly succeed here while the identical filter is refused everywhere else. Use a literal bound, or spell the comparison you meant as a scalar one ({ "${field}": { "$gte": { "$field": "${ref}" } } }), which IS served \u2014 on the ObjectQL engine path, where the driver enforces the #5222 rulings (#7598).`;
 }
 function unbindableListMemberMessage(op, field, value, index) {
-  return `"${op}" on "${field}" has a value at index ${index} of its list that cannot be bound as a SQL parameter: ${shapePreview(value)}. Every member of an $in/$nin/$between list is a comparand in its own right \u2014 use a string, number, boolean, null, Date or binary value. Refusing rather than binding it: the member can equal no stored value, so the list silently loses that entry (and a $nin loses the exclusion the caller wrote).`;
+  return `"${op}" on "${field}" has a value at index ${index} of its list that cannot be bound as a SQL parameter: ${shapePreview(value)}. Every member of an $in/$nin/$between list is a comparand in its own right \u2014 use ${import_data.ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} (or a binary value). Refusing rather than binding it: the member can equal no stored value, so the list silently loses that entry (and a $nin loses the exclusion the caller wrote).`;
 }
 
 // src/strategies/filter-normalizer.ts
@@ -586,7 +628,7 @@ function nullSafeNegationOperand(node) {
 }
 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].`
+    `[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_data2.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) {
@@ -595,8 +637,8 @@ function lowerAnalyticsWhere(query) {
   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 (!(0, import_data2.isFilterAST)(where)) throw filterArrayNotLowerableError(where);
+    const condition = (0, import_data2.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).`
@@ -1019,16 +1061,33 @@ function invalidMemberError(message, meta) {
 }
 
 // src/strategies/native-sql-strategy.ts
-var import_core = require("@objectstack/core");
+var import_core2 = require("@objectstack/core");
 var AGGREGATE_SQL = {
-  "count": () => "COUNT(*)",
+  // [#10298] `count` takes its COLUMN when the measure declares one. The
+  // wrapper used to discard `col` and always emit `COUNT(*)`, so a measure
+  // written `{ aggregate: 'count', field: 'resolved_by_article' }` counted
+  // ROWS instead of non-null values — and a deflection rate built as
+  // `kb_resolved_count / closed_count` read 100% where the truth was 12.5%,
+  // with the numerator and denominator printed beside it as 8 and 8. `*` is
+  // still `COUNT(*)`: the compiler writes `sql: m.field ?? '*'`, so the star
+  // IS the "no field declared" spelling and must keep counting rows.
+  "count": (col) => col === "*" ? "COUNT(*)" : `COUNT(${col})`,
   "sum": (col) => `SUM(${col})`,
   "avg": (col) => `AVG(${col})`,
   "min": (col) => `MIN(${col})`,
   "max": (col) => `MAX(${col})`,
   "count_distinct": (col) => `COUNT(DISTINCT ${col})`
 };
+var CONDITIONAL_AGGREGATE_SQL = {
+  "count": (col, pred) => `COUNT(CASE WHEN ${pred} THEN ${col === "*" ? "1" : col} END)`,
+  "sum": (col, pred) => `SUM(CASE WHEN ${pred} THEN ${col} END)`,
+  "avg": (col, pred) => `AVG(CASE WHEN ${pred} THEN ${col} END)`,
+  "min": (col, pred) => `MIN(CASE WHEN ${pred} THEN ${col} END)`,
+  "max": (col, pred) => `MAX(CASE WHEN ${pred} THEN ${col} END)`,
+  "count_distinct": (col, pred) => `COUNT(DISTINCT CASE WHEN ${pred} THEN ${col} END)`
+};
 var SUPPORTED_AGGREGATE_SQL_KEYS = Object.keys(AGGREGATE_SQL);
+var CONDITIONAL_AGGREGATE_SQL_KEYS = Object.keys(CONDITIONAL_AGGREGATE_SQL);
 var EXPRESSION_METRIC_TYPES = /* @__PURE__ */ new Set(["number", "string", "boolean"]);
 var IDENTIFIER_PATH = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 var NativeSQLStrategy = class {
@@ -1051,9 +1110,51 @@ var NativeSQLStrategy = class {
       }
     }
     if (this.carriesCrossFieldComparison(query, ctx)) return false;
+    if (this.carriesUninterpretableTemporalComparand(query, ctx)) return false;
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === "function";
   }
+  /**
+   * [#8690] Does the query's `where` compare a declared TIME dimension against
+   * a value no temporal storage rule can read? See the ruling at
+   * {@link canHandle}.
+   *
+   * The classification comes from the CUBE, the only metadata this package has:
+   * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+   * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+   * member lookup in this strategy uses, so "the member the gate classified"
+   * and "the member the compiler emits" cannot drift apart.
+   *
+   * A `time` dimension is read with the DATETIME rule — the permissive one of
+   * the three. That is the right direction because this is a routing decision,
+   * not a verdict: the engine door re-judges with the field's real declared
+   * type and has the final say, so under-classifying an exotic spelling merely
+   * leaves today's behaviour, while over-classifying would silently move a
+   * working dashboard off the fast path. The comparands this card measured
+   * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+   * so the decline fires for them whichever backing type the dimension has.
+   *
+   * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+   * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+   * lowering is not this gate's to answer — the filter is malformed either way
+   * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+   * message and envelope it has always had.
+   */
+  carriesUninterpretableTemporalComparand(query, ctx) {
+    const cube = query.cube ? ctx.getCube(query.cube) : void 0;
+    if (!cube) return false;
+    let where = null;
+    try {
+      where = lowerAnalyticsWhere(query);
+    } catch {
+      return false;
+    }
+    if (!where) return false;
+    return findUninterpretableTemporalMember(
+      where,
+      (member) => this.lookupMember(cube, member, "dimension")?.type === "time" ? "datetime" : null
+    ) !== null;
+  }
   /**
    * [#7598] Does serving this query require the cross-field capability this
    * strategy declines? See the ruling recorded at {@link canHandle}.
@@ -1152,9 +1253,19 @@ var NativeSQLStrategy = class {
         groupByClauses.push(colExpr);
       }
     }
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
     if (query.measures && query.measures.length > 0) {
       for (const measure of query.measures) {
-        const aggExpr = this.resolveMeasureSql(cube, measure, tableName, joins);
+        const measureFilter = datasetScope?.measureFilters?.[measure];
+        const predicate = measureFilter ? this.compileFilterNode(
+          normalizeAnalyticsFilterTree({ where: measureFilter }),
+          cube,
+          tableName,
+          joins,
+          params,
+          ctx
+        ) : null;
+        const aggExpr = this.resolveMeasureSql(cube, measure, tableName, joins, predicate);
         selectClauses.push(`${aggExpr} AS "${measure}"`);
       }
     }
@@ -1168,6 +1279,17 @@ var NativeSQLStrategy = class {
       ctx
     );
     if (filterSql) whereClauses.push(filterSql);
+    if (datasetScope?.filter) {
+      const scopeSql = this.compileFilterNode(
+        normalizeAnalyticsFilterTree({ where: datasetScope.filter }),
+        cube,
+        tableName,
+        joins,
+        params,
+        ctx
+      );
+      if (scopeSql) whereClauses.push(scopeSql);
+    }
     if (query.timeDimensions && query.timeDimensions.length > 0) {
       for (const td of query.timeDimensions) {
         const colExpr = this.resolveFieldSql(cube, td.dimension, tableName, joins);
@@ -1176,7 +1298,7 @@ var NativeSQLStrategy = class {
           if (range.length === 2) {
             const td2 = this.resolveStorageTarget(cube, td.dimension, tableName);
             const column = this.temporalColumn(ctx, td2, colExpr);
-            const nextDay = (0, import_core.nextUtcCalendarDay)(range[1]);
+            const nextDay = (0, import_core2.nextUtcCalendarDay)(range[1]);
             params.push(this.coerceTemporal(ctx, td2, range[0]));
             const lower = `${column} >= $${params.length}`;
             if (nextDay != null) {
@@ -1341,7 +1463,12 @@ var NativeSQLStrategy = class {
     const raw = dim ? dim.sql : member.includes(".") ? member.split(".")[1] : member;
     return this.qualifyAndRegisterJoin(raw, parentTable, joins, cube);
   }
-  resolveMeasureSql(cube, member, parentTable, joins) {
+  /**
+   * @param predicate - The measure's own scoped filter, already compiled to a
+   *   SQL boolean (`null` = the measure declares none, or declares one that
+   *   constrains nothing — `compileFilterNode`'s TRUE). #10298.
+   */
+  resolveMeasureSql(cube, member, parentTable, joins, predicate = null) {
     const measure = this.lookupMember(cube, member, "measure");
     if (!measure) {
       const declared = Object.keys(cube.measures ?? {});
@@ -1351,6 +1478,13 @@ var NativeSQLStrategy = class {
       );
     }
     const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins, cube);
+    if (predicate !== null) {
+      const wrapConditional = CONDITIONAL_AGGREGATE_SQL[measure.type];
+      if (wrapConditional) return wrapConditional(col, predicate);
+      throw new Error(
+        `[native-sql-strategy] measure "${member}" on cube "${cube.name}" carries a scoped filter, but its type "${measure.type}" has no conditional form (conditional: ${CONDITIONAL_AGGREGATE_SQL_KEYS.join(", ")}).`
+      );
+    }
     const wrap = AGGREGATE_SQL[measure.type];
     if (wrap) return wrap(col);
     if (EXPRESSION_METRIC_TYPES.has(measure.type)) return col;
@@ -1546,7 +1680,7 @@ var NativeSQLStrategy = class {
       return `${rawCol} ${sqlOp} ${patternRef} ESCAPE $${params.length}`;
     }
     if (operator === "lte") {
-      const nextDay = (0, import_core.nextUtcCalendarDay)(values[0]);
+      const nextDay = (0, import_core2.nextUtcCalendarDay)(values[0]);
       if (nextDay != null) {
         params.push(this.coerceTemporal(ctx, target, nextDay));
         return `${this.temporalColumn(ctx, target, rawCol)} < $${params.length}`;
@@ -1576,8 +1710,8 @@ var NativeSQLStrategy = class {
 };
 
 // src/strategies/objectql-strategy.ts
-var import_data2 = require("@objectstack/spec/data");
-var import_core2 = require("@objectstack/core");
+var import_data3 = require("@objectstack/spec/data");
+var import_core3 = require("@objectstack/core");
 
 // src/strategies/cross-object-rebucket.ts
 var RECOMBINABLE_METHODS = /* @__PURE__ */ new Set([
@@ -1697,10 +1831,18 @@ var ObjectQLStrategy = class {
       const extra = this.mergeFilterOperand(filter, field, bounds);
       if (extra) conjuncts.push(extra);
     }
+    const datasetScope = ctx.getDatasetScope?.(query.cube);
+    if (datasetScope?.filter) {
+      const scopeCondition = this.filterNodeToCondition(
+        normalizeAnalyticsFilterTree({ where: datasetScope.filter }),
+        cube
+      );
+      if (scopeCondition) conjuncts.push(scopeCondition);
+    }
     if (conjuncts.length > 0) {
       filter.$and = [...Array.isArray(filter.$and) ? filter.$and : [], ...conjuncts];
     }
-    const plan = this.planCrossObject(cube, query, filter);
+    const plan = this.planCrossObject(cube, query, this.filterMemberView(cube, query, ctx));
     if (plan) {
       return this.executeCrossObject(cube, query, aggregations, filter, plan, ctx);
     }
@@ -1777,9 +1919,7 @@ var ObjectQLStrategy = class {
       if (td.granularity) granByDim.set(td.dimension, td.granularity);
     }
     const tableName = this.extractObjectName(cube);
-    const plan = this.planCrossObject(cube, query, Object.fromEntries(
-      collectFilterLeaves(normalizeAnalyticsFilterTree(query)).map((f) => [this.resolveFieldName(cube, f.member, "any"), true])
-    ));
+    const plan = this.planCrossObject(cube, query, this.filterMemberView(cube, query, ctx));
     const crossByDim = new Map((plan?.crossDims ?? []).map((cd) => [cd.outputName, cd]));
     const joinClauses = [];
     const dimExpr = (dim) => {
@@ -1821,8 +1961,17 @@ var ObjectQLStrategy = class {
       params
     );
     if (filterClause) whereParts.push(filterClause);
+    const echoedDatasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
+    if (echoedDatasetFilter) {
+      const scopeSql = this.renderFilterNodeSql(
+        normalizeAnalyticsFilterTree({ where: echoedDatasetFilter }),
+        cube,
+        params
+      );
+      if (scopeSql) whereParts.push(scopeSql);
+    }
     for (const { field, bounds } of this.dateRangeBounds(cube, query)) {
-      const nextDay = (0, import_core2.nextUtcCalendarDay)(bounds.$lte);
+      const nextDay = (0, import_core3.nextUtcCalendarDay)(bounds.$lte);
       params.push(bounds.$gte, nextDay ?? bounds.$lte);
       whereParts.push(
         `(${field} >= $${params.length - 1} AND ${field} ${nextDay ? "<" : "<="} $${params.length})`
@@ -1873,11 +2022,11 @@ var ObjectQLStrategy = class {
    * predicate. `$and` makes that structurally impossible.
    */
   withReadScope(objectName, filter, ctx) {
-    const userFilter = Object.keys(filter).length > 0 ? (0, import_data2.markFilterSubtreeProvenance)(filter, "author") : void 0;
+    const userFilter = Object.keys(filter).length > 0 ? (0, import_data3.markFilterSubtreeProvenance)(filter, "author") : void 0;
     if (typeof ctx.getReadScope !== "function") return userFilter;
     const scope = ctx.getReadScope(objectName);
     if (scope === void 0 || scope === null) return userFilter;
-    const scopeFilter = (0, import_data2.markFilterSubtreeProvenance)(scope, "policy");
+    const scopeFilter = (0, import_data3.markFilterSubtreeProvenance)(scope, "policy");
     if (!userFilter) return scopeFilter;
     return { $and: [userFilter, scopeFilter] };
   }
@@ -1888,6 +2037,68 @@ var ObjectQLStrategy = class {
     const joinedObject = cube.joins?.[alias]?.name ?? alias;
     return joinedObject !== baseObject;
   }
+  /**
+   * The member view {@link planCrossObject} judges a filter by: EVERY member
+   * that will end up in the engine's predicate, structure discarded, keyed by
+   * RESOLVED field name (#10759), valued by WHERE THE MEMBER CAME FROM
+   * (#10861).
+   *
+   * Both call sites — `execute()` and `generateSql()` — are handed this and
+   * nothing else, which is what makes the invariant `planCrossObject` states
+   * for itself ("the preview accepts/rejects the same set") structural rather
+   * than a coincidence maintained by hand. They used to build the view
+   * separately: the echo flattened the tree, `execute()` passed the ENGINE
+   * FILTER, and a filter record answers a different question — it is a
+   * predicate to evaluate, not an inventory of members. An `$or`, a `$not` or
+   * an unmergeable nested `$and` travels in it as one opaque `$and` entry, so
+   * the members inside were unreadable from the outside and the envelope check
+   * could not reject what it could not see.
+   *
+   * ## Two producers, one inventory (#10861)
+   *
+   * The caller's `where` is not the only thing that reaches `engine.aggregate`
+   * as a predicate. Since PR #10758 the compiled dataset's own definition-level
+   * `filter` is lowered onto `execute()`'s `conjuncts` and rendered by
+   * `generateSql()`, so a dataset declaring `filter: { 'account.region': 'West' }`
+   * sent `{"$and":[{"account.region":"West"}]}` to an engine that cannot join —
+   * measured on both doors, which AGREED in accepting it, so #10759's
+   * preview/execution symmetry had nothing to restore. Refusing it is a
+   * widening of the refusal set, ruled by the maintainer on 2026-08-22 (Option
+   * A, query-time refusal): fold the scope's leaves in HERE, where driver
+   * capability is known, rather than in `dataset-compiler.ts`, which cannot see
+   * which driver will serve the dataset and would refuse a dataset that is
+   * perfectly legal on a native-SQL deployment.
+   *
+   * Structure is discarded on purpose — a member is cross-object or it is not,
+   * and which branch of a disjunction it sits in cannot make
+   * `engine.aggregate` able to join it. PROVENANCE is not discarded, because it
+   * decides what the refusal can tell the caller to go fix: `AnalyticsRequestKey`
+   * is the analytics REQUEST vocabulary and a dataset's `filter` is not in it,
+   * so a scope-borne member must not be reported as `param: 'where'` — see
+   * `planCrossObject`. The value slot carries that and nothing else; it never
+   * reaches a driver.
+   *
+   * Dataset leaves are inserted FIRST so a member named by BOTH producers keeps
+   * the caller's provenance (last write wins on a duplicate key): if it is in
+   * the request too, the request is the actionable place to fix it.
+   *
+   * Time-dimension WINDOWS are deliberately absent (they live in
+   * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
+   * time dimension is refused by `planCrossObject`'s own first loop, over
+   * `query.timeDimensions`, and refused as the time dimension the author wrote
+   * rather than as the lowered predicate it becomes — which is the better
+   * diagnostic and the reason that loop runs first.
+   */
+  filterMemberView(cube, query, ctx) {
+    const datasetFilter = ctx.getDatasetScope?.(query.cube)?.filter;
+    const leaves = (node, origin) => collectFilterLeaves(node).map(
+      (f) => [this.resolveFieldName(cube, f.member, "any"), origin]
+    );
+    return Object.fromEntries([
+      ...datasetFilter ? leaves(normalizeAnalyticsFilterTree({ where: datasetFilter }), "dataset-filter") : [],
+      ...leaves(normalizeAnalyticsFilterTree(query), "where")
+    ]);
+  }
   /**
    * Plan how to serve cross-object references on this join-less path (#3654).
    *
@@ -1898,21 +2109,36 @@ var ObjectQLStrategy = class {
    * query (direct path), a plan for an in-envelope cross-object query.
    *
    * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
-   * (needs a real join to evaluate), a MULTI-HOP dimension (`a.b.c`), or a
+   * (needs a real join to evaluate), a cross-object leaf in the DATASET's own
+   * definition-level `filter` (#10861 — same join it does not have, arriving
+   * from the producer PR #10758 added), a MULTI-HOP dimension (`a.b.c`), or a
    * non-recombinable measure (`avg`/`count_distinct`, whose sub-bucket values
    * 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.
+   * `generateSql()` calls this too, so the preview accepts/rejects the same set
+   * — and since #10759 both callers derive `filter` from the one
+   * {@link filterMemberView}, so that sentence is enforced by construction
+   * instead of restated at two call sites.
    *
-   * [#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.
+   * [#5716] All five refusals below are `invalidMemberError` — `INVALID_FIELD` /
+   * 400, naming the member — and the four that predate #10861 keep their
+   * MESSAGES unchanged (they are good diagnostics, and #5923's tests read
+   * them). Each is decided by two facts and nothing else: a member that will
+   * reach the engine's predicate, 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 every 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
+   * four of them fire on `/analytics/query` where no dataset exists.
+   *
+   * [#10861] The fifth is the exception that proves the rule and is written to
+   * it: it can only fire where a dataset DOES exist, and it is the one refusal
+   * here whose member no request key named — so it carries `cube` and no
+   * `param`, and says in its own words which document to go and edit. It stays
+   * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
+   * is the same physical one as its neighbour — this engine cannot join this
+   * member — and splitting the code by PROVENANCE would make a caller branch on
+   * two wire shapes for one capability limit.
    *
    * Detection is on RESOLVED field names, so a dotted dimension the cube
    * flattens to a real column is treated as base, not cross-object.
@@ -1934,7 +2160,7 @@ var ObjectQLStrategy = class {
         member: m,
         field: this.resolveMeasureAggregation(cube, m).field
       })),
-      ...Object.keys(filter).map((f) => ({ where: "filter", member: f, field: f }))
+      ...Object.entries(filter).filter(([, origin]) => origin === "where").map(([f]) => ({ where: "filter", member: f, field: f }))
     ].filter((r) => this.isCrossObjectField(cube, r.field, baseObject));
     if (nonDim.length > 0) {
       throw invalidMemberError(
@@ -1948,6 +2174,13 @@ var ObjectQLStrategy = class {
         }
       );
     }
+    const scopeCross = Object.entries(filter).filter(([field, origin]) => origin === "dataset-filter" && this.isCrossObjectField(cube, field, baseObject)).map(([field]) => field);
+    if (scopeCross.length > 0) {
+      throw invalidMemberError(
+        `[Analytics] ObjectQLStrategy cannot evaluate the cross-object filter ("${scopeCross[0]}") that dataset "${cube.name}" declares at its definition level \u2014 the engine cannot join in an aggregate, so this predicate matches nothing and the answer would be neither the scoped number nor the unscoped one. Nothing in the request names it: remove the cross-object leaf from the dataset's own \`filter\`, or serve this dataset on a native-SQL driver, where the same definition is valid.`,
+        { member: scopeCross[0], cube: cube.name }
+      );
+    }
     const crossDims = [];
     for (const dim of query.dimensions ?? []) {
       const field = this.resolveFieldName(cube, dim, "dimension");
@@ -2051,7 +2284,7 @@ var ObjectQLStrategy = class {
     if (fkValues.length === 0 || typeof ctx.executeAggregate !== "function") return map;
     const idFilter = { id: { $in: fkValues } };
     const scope = typeof ctx.getReadScope === "function" ? ctx.getReadScope(refObject) : null;
-    if (scope != null) (0, import_data2.markFilterSubtreeProvenance)(scope, "policy");
+    if (scope != null) (0, import_data3.markFilterSubtreeProvenance)(scope, "policy");
     const filter = scope != null ? { $and: [idFilter, scope] } : idFilter;
     const rows = await ctx.executeAggregate(refObject, {
       groupBy: ["id", attr],
@@ -2543,10 +2776,10 @@ var ObjectQLStrategy = class {
 };
 
 // src/dataset-compiler.ts
-var import_data3 = require("@objectstack/spec/data");
+var import_data4 = require("@objectstack/spec/data");
 var import_ui = require("@objectstack/spec/ui");
 var UNSUPPORTED_AGGREGATES = /* @__PURE__ */ new Set();
-var SUPPORTED_AGGREGATES = import_data3.AggregationFunction.options.filter((a) => !UNSUPPORTED_AGGREGATES.has(a));
+var SUPPORTED_AGGREGATES = import_data4.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`);
@@ -2708,11 +2941,11 @@ function compileDataset(dataset, resolver, options) {
 }
 
 // src/dataset-executor.ts
-var import_data4 = require("@objectstack/spec/data");
-var import_core3 = require("@objectstack/core");
+var import_data5 = require("@objectstack/spec/data");
+var import_core4 = require("@objectstack/core");
 function resolveSelectionTokens(compiled, selection, context) {
-  const tokenCtx = (0, import_core3.filterTokenContextFrom)(context, /* @__PURE__ */ new Date());
-  const resolve = (v) => (0, import_core3.resolveFilterTokens)(v, tokenCtx);
+  const tokenCtx = (0, import_core4.filterTokenContextFrom)(context, /* @__PURE__ */ new Date());
+  const resolve = (v) => (0, import_core4.resolveFilterTokens)(v, tokenCtx);
   const filter = resolve(compiled.filter);
   const measureFilters = resolve(compiled.measureFilters);
   const runtimeFilter = resolve(selection.runtimeFilter);
@@ -2748,7 +2981,7 @@ function evaluateDerivedMeasures(rows, derived) {
 }
 function fillEmptyGroups(rows, columnAggregates) {
   for (const [column, aggregate2] of Object.entries(columnAggregates)) {
-    const empty = (0, import_data4.emptyGroupValueFor)(aggregate2);
+    const empty = (0, import_data5.emptyGroupValueFor)(aggregate2);
     if (empty === void 0) continue;
     for (const row of rows) if (row[column] == null) row[column] = empty;
   }
@@ -2948,7 +3181,7 @@ function bucketKeyAtOrdinal(ordinal, granularity) {
 }
 function alignedCompareBucketKey(key, granularity, kind, currentRange, shiftedRange) {
   if (typeof key !== "string" || key.length === 0) return null;
-  const span = (0, import_core3.bucketKeyToCalendarRange)(key, granularity);
+  const span = (0, import_core4.bucketKeyToCalendarRange)(key, granularity);
   if (!span) return null;
   const targetOrdinal = kind === "previousYear" ? bucketOrdinalOfDay(shiftYear(span.start, 1), granularity) : bucketOrdinalOfDay(span.start, granularity) + (bucketOrdinalOfDay(currentRange[0], granularity) - bucketOrdinalOfDay(shiftedRange[0], granularity));
   const first = bucketOrdinalOfDay(currentRange[0], granularity);
@@ -3412,18 +3645,18 @@ function pickDisplayField(fields) {
 }
 
 // src/preview-evaluator.ts
-var import_core4 = require("@objectstack/core");
+var import_core5 = require("@objectstack/core");
 function compare(a, b) {
   if (typeof a === "number" && typeof b === "number") return a - b;
   if (a instanceof Date || b instanceof Date) {
-    const ai = (0, import_core4.utcInstantMs)(a);
-    const bi = (0, import_core4.utcInstantMs)(b);
+    const ai = (0, import_core5.utcInstantMs)(a);
+    const bi = (0, import_core5.utcInstantMs)(b);
     if (ai !== null && bi !== null) return ai - bi;
   }
   return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
 }
 function lteBound(value, bound) {
-  const nextDay = (0, import_core4.nextUtcCalendarDay)(bound);
+  const nextDay = (0, import_core5.nextUtcCalendarDay)(bound);
   if (nextDay != null) return compare(value, nextDay) < 0;
   return compare(value, bound) <= 0;
 }
@@ -3481,7 +3714,7 @@ function matchesWhere(row, where) {
 function bucketDate(value, granularity, timezone) {
   const d = new Date(String(value));
   if (Number.isNaN(d.getTime())) return null;
-  const { year: y, month, day: dayNum } = (0, import_core4.calendarPartsInTzOrUtc)(d, timezone);
+  const { year: y, month, day: dayNum } = (0, import_core5.calendarPartsInTzOrUtc)(d, timezone);
   const m = `${month}`.padStart(2, "0");
   const day = `${dayNum}`.padStart(2, "0");
   switch (granularity) {
@@ -3535,7 +3768,7 @@ function evaluateAnalyticsQueryOverRows(query, cube, rows) {
     const [start, end] = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
     filtered = filtered.filter((r) => {
       const v = String(r[field] ?? "");
-      const nextDay = (0, import_core4.nextUtcCalendarDay)(end);
+      const nextDay = (0, import_core5.nextUtcCalendarDay)(end);
       const inUpper = nextDay != null ? v < nextDay : v <= `${end}~`;
       return v >= String(start) && inUpper;
     });
@@ -3669,7 +3902,7 @@ var AnalyticsService = class {
     this.datasetRegistry = /* @__PURE__ */ new Map();
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     this.warnedNoObjectRegistry = false;
-    this.logger = config.logger || (0, import_core5.createLogger)({ level: "info", format: "pretty" });
+    this.logger = config.logger || (0, import_core6.createLogger)({ level: "info", format: "pretty" });
     this.cubeRegistry = new CubeRegistry();
     if (config.cubes) {
       this.cubeRegistry.registerAll(config.cubes);
@@ -3683,7 +3916,7 @@ var AnalyticsService = class {
     this.getObjectFieldNames = config.getObjectFieldNames;
     this.getObjectDatasource = config.getObjectDatasource;
     this.isExternalObject = config.isExternalObject;
-    this.debugSql = config.debugSql ?? (0, import_core5.getEnv)("NODE_ENV") === "development";
+    this.debugSql = config.debugSql ?? (0, import_core6.getEnv)("NODE_ENV") === "development";
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -3702,6 +3935,16 @@ var AnalyticsService = class {
       // Prefer a compiled dataset's declared relationships (D-C join allowlist);
       // fall back to any explicitly-configured provider for legacy cubes.
       getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName),
+      // [#10298] The compiled dataset's definition-level filter and its
+      // per-measure filters — the half of the declaration the Cube model has
+      // no room for. Same shape and same registry as `getAllowedRelationships`
+      // directly above: answered for a cube that IS a compiled dataset,
+      // `undefined` for every other cube.
+      getDatasetScope: (cubeName) => {
+        const compiled = this.datasetRegistry.get(cubeName);
+        if (!compiled) return void 0;
+        return { filter: compiled.filter, measureFilters: compiled.measureFilters };
+      },
       coerceTemporalFilterValue: config.coerceTemporalFilterValue,
       coerceTemporalFilterColumn: config.coerceTemporalFilterColumn,
       isExternalObject: config.isExternalObject
@@ -3948,11 +4191,11 @@ var AnalyticsService = class {
       else if (rangeTz === "UTC") rangeDims.push({ d, granularity, instant: false });
     }
     if (rangeDims.length && result.rows.length) {
-      const bound = (ymd, instant) => instant ? new Date((0, import_core5.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
+      const bound = (ymd, instant) => instant ? new Date((0, import_core6.zonedDateStartToUtcMs)(ymd, rangeTz)).toISOString() : ymd;
       result.drillRanges = result.rows.map((row) => {
         const ranges = {};
         for (const { d, granularity, instant } of rangeDims) {
-          const cal = (0, import_core5.bucketKeyToCalendarRange)(row[d.name], granularity);
+          const cal = (0, import_core6.bucketKeyToCalendarRange)(row[d.name], granularity);
           if (cal) {
             ranges[d.name] = { field: d.field, gte: bound(cal.start, instant), lt: bound(cal.end, instant) };
           }
@@ -4003,7 +4246,7 @@ var AnalyticsService = class {
           }
         }
         if (f.percentScale == null) {
-          f.percentScale = m.derived?.op === "ratio" ? "fraction" : (0, import_data5.percentScaleOf)(meta);
+          f.percentScale = m.derived?.op === "ratio" ? "fraction" : (0, import_data6.percentScaleOf)(meta);
         }
       }
     }